# BuildWithHQ Support: full documentation corpus

Source index: https://support.buildwithhq.com/llms.txt
AI support feed: https://support.buildwithhq.com/ai/support-content.jsonl
OpenAPI JSON: https://support.buildwithhq.com/openapi/buildwithhq.json
Pinned OpenAPI JSON: https://support.buildwithhq.com/openapi/versions/1.20.70/buildwithhq.json

---

# Section: Getting Started

---
title: "What is BuildWithHQ?"
section: "Getting Started"
canonical_url: "https://support.buildwithhq.com/getting-started/what-is-buildwithhq.html"
reviewed_at: "2026-10-22"
authority: Official
---

# What is BuildWithHQ?

The platform in plain terms: build, brand, and resell your own SaaS applications.

## In brief

- **Audience:** New builders
- **Reading time:** 4 min
- **Requires:** Nothing yet

BuildWithHQ is a platform for creating software products you sell to your own customers. You design the application — its pages, data, workflows, and AI features — and BuildWithHQ runs the infrastructure behind it: databases, hosting, payments, security, and AI processing.

## Three roles to know

- **Builder** — that's you. You create and configure applications in the builder console, and you own the relationship with your customers.
- **Tenant** — a customer company that signs up for one of your applications. Each tenant's data is isolated from every other tenant's.
- **End user** — a person at a tenant company who logs into your application day to day.

## What the platform runs for you

Each application uses routed database planes for live application data, audit history and AI. App creation starts a staged provisioning operation. Check its readiness and any reported setup requirements before inviting customers; creating an app record does not establish that its databases, domain and workers are ready.

## What you can build today

- **Professional tenant applications** — compose and publish TailAdmin-derived React/Puck pages, app themes, custom CSS, design assets, menus, User Types, DataRoles, and Locations.
- **Complete business workflows** — use first-class modules and dynamic fields with create, view, edit, safe removal, favorites, files, activity, and recursive record relationships.
- **AI-assisted products** — add permission-filtered multimodal search, Knowledge Core, AI Insights, Universal Inbox, and approval-governed GoClaw actions.
- **Headless or embedded products** — use the versioned Developer API, typed SDK, webhooks, MCP, body-only pages, or complete page shells while credentials and database routing remain server-owned.
- **Extensible SaaS products** — install exact-version marketplace features, discover their per-app API schemas, and run approved appliance services without giving extensions direct tenant authority.

Note

Your customers never see BuildWithHQ. Applications run under your brand, on your domains, with your logo and colors.

## Where to go next

Continue with [Create your account](../getting-started/create-your-account.html), then [Launch your first app](../getting-started/your-first-app.html). If you learn best by looking at the end result first, skim [the page editor](../builder-guide/page-editor.html)  to see how apps are assembled.

---

Capability review: 2026-10-22. [View the canonical guide](https://support.buildwithhq.com/getting-started/what-is-buildwithhq.html).

---
title: "Current features and setup requirements"
section: "Getting Started"
canonical_url: "https://support.buildwithhq.com/getting-started/current-features.html"
reviewed_at: "2026-10-23"
authority: Official
---

# Current features and setup requirements

Find the current page designer, record scope, AI, API, integrations and diagnostics guidance, and check what your app has enabled.

## In brief

- **Guide updated:** 23 October 2026
- **Audience:** Builders and app users
- **Availability:** App configuration and permissions apply

BuildWithHQ combines a page designer, connected business records and governed automation for SaaS products. Your published app, entitlements, permissions and configured services determine which capabilities you can use. A feature described here or a visible control does not establish that a provider, model server or worker is running.

## Design and publish pages

Compose registered React components in the Puck page designer. Configure themes, custom CSS, assets, menus and User Types, save drafts, preview the result and publish the intended version. User Types select homepages, layouts and menus. Record authority still comes from the signed-in user’s Personal ownership, DataRoles, Locations and action permissions. A page being absent from a menu does not by itself deny access to an entitled published page.

## Choose record visibility explicitly

For records that support Personal, choose Personal or one eligible DataRole. Chat Rooms, Discussion Boards, Knowledge and Company News are shared-only and require one DataRole. Files offers Personal while you have room under your personal file limit. When shared records require a location, choose an authorized location or All if you have all-location access. Leaving a selection blank is not All. Child records inherit the parent’s scope. Read [Record visibility: Personal, DataRoles and Locations](record-visibility.html)  before creating or moving shared data.

## Use the modules enabled in your app

Connected modules include contacts, organizations, tasks, checklists, work orders, conversations, files and knowledge. Open the native module for the allowed create, view, edit and removal actions. Some removals archive, cancel or deactivate a record to preserve its history. Search, dashboards and activity projections lead back to that native record rather than duplicating its lifecycle. The [module inventory](../first-class-modules/index.html)  describes individual surfaces and boundaries.

## Keep Inbox and AI actions governed

Chat rooms and messages require current membership as well as DataRole and location access, including through Graph, Activity, Favorites and direct record links. Use native Chat Rooms search to find them: general and AI search exclude chat content. Saves check current permissions again. Removing a room preserves its history through soft deletion; an authorized restore restores only messages hidden by that room removal. Individually removed messages stay removed. See [Chat rooms](../first-class-modules/chat-rooms.html).

Universal Inbox collects attention while conversations, submissions and business records remain their source records. Refresh an item that has changed before approving a suggested action. GoClaw planning and research are read-only; material changes require the configured approval policy and action permission, and execution must use the approved current context. A suggestion, an approval and a queued execution are distinct states.

AI search and Knowledge Core apply the current user’s record, field, DataRole, location and AI-read permissions before assembling model context. Multimodal retrieval can preserve both text and visual evidence. Ingestion, serving and execution depend on configured and enabled services; contact your operator when the app reports a dependency is unavailable.

## Connect a headless app, SDK or MCP client

Start with the [generated OpenAPI reference](../api/interactive-api-reference.html)  and current versioned Developer Kit. The public API contract is distinct from native browser-only routes. Keep app keys and delegated tokens in trusted server storage. OAuth connections and MCP do not replace tenant identity or record permissions. Sensitive MCP capabilities require explicit app-level approval; connecting a client does not authorize every write. Use the exact documented route and the latest concurrency token, and refresh state after a conflict rather than replaying a consequential request blindly.

## Verify external services before enabling work

Mail, payment processing, webhooks, Snowflake export and automation depend on configured providers and running workers. Verify the destination and credentials for the selected organization, test the connection and explicitly enable supported processing or schedules. A queued reply is not a delivered message, a transfer submission is not bank settlement, and a saved integration is not an active worker. See the [Snowflake setup and export guide](../api/tenant-snowflake.html)  for its test, enable and schedule steps.

## Protect sensitive values

Supported Contact secure fields use masked display and an explicit permission-checked reveal. Keep secrets out of ordinary fields and support messages. Do not assume that every module has an operational encryption and reveal flow; the [secure-field guide](../builder-guide/secure-fields.html)  distinguishes available contracts and setup requirements.

## Find the evidence for a problem

Authorized builders can open [+ Debug](../builder-guide/debug-drawer.html)  for safe outcomes, timings and correlation references, then follow a problem to app Logs. Use its sanitized export for support. Closing a problem preserves its history; another occurrence can reopen it. Do not paste customer payloads, credentials or private keys into a ticket.

## Wait for app readiness

App creation and infrastructure readiness are separate stages. An app has routed Core, Logs and AI database planes; inspect provisioning status and resolve reported setup requirements before inviting customers. A new app record is not proof that databases, DNS, certificates, compute and workers are ready. Exact-version template installs configure presentation; database updates follow a separate reviewed path. Customer-hosted Appliance operation and optional extension compute have separate deployment requirements.

For incidents use [service status](https://status.buildwithhq.com/). A stale or unavailable feed cannot confirm health. Blog product ideas, conference topics and interface previews explain possibilities; they do not certify a live app or production launch.

---

Capability review: 2026-10-23. [View the canonical guide](https://support.buildwithhq.com/getting-started/current-features.html).

---
title: "Record visibility: Personal, DataRoles and Locations"
section: "Getting Started"
canonical_url: "https://support.buildwithhq.com/getting-started/record-visibility.html"
reviewed_at: "2026-10-23"
authority: Official
---

# Record visibility: Personal, DataRoles and Locations

Choose an explicit scope when creating records, understand inherited child visibility, and safely update shared records.

## In brief

- **Applies to:** User-managed business records
- **Choose on:** Top-level create or scope move
- **Authority:** Verified user and current permissions

## Create a Personal record where supported

When the module offers **Personal** in its visibility choices, select it explicitly. The record belongs to you, has no location and gives its owner control. Another user’s membership in your organization does not make your Personal record shared.

## Shared-only modules

Chat Rooms, Discussion Boards, Knowledge and Company News do not offer Personal for new records. Choose one eligible DataRole and, when required, an authorized location or All. Chat rooms and messages additionally require current room membership. They remain accessible through native Chat Rooms search, while general and AI search exclude chat content.

## Personal files

Files offers Personal up to a per-person limit: the app sets a default (25 unless the builder changes it, in the Design studio under Files) and a ceiling, and the organization owner can choose any number up to the ceiling in Account admin > File storage, where 0 turns personal files off. The upload form shows how many personal files you have used. Deleted personal files count until they are permanently removed, and lowering the limit never removes files people already have.

## Create a shared record

1. Select one **DataRole** in which you are allowed to create this kind of record. App navigation and your User Type do not choose a DataRole for you.
2. When active Locations exist, select one authorized location. Select **All** only if you have all-location access. An empty selection is not All, even if there is only one choice.
3. Save the record. The server checks your current authority and commits the record and its selected scope together.

When there are no active Locations, the location field is optional. If no eligible scope choices are available, ask your administrator for the relevant permission rather than attempting to bypass the form.

## Add a child record

Create the child from its authorized parent. The child inherits that parent’s DataRole and location within the create operation. Do not select a different scope to make a child visible outside its parent.

## Edit or move an existing record

Review the displayed current scope. You do not need to reselect scope for an ordinary edit; explicitly choose the destination when moving a record. The destination still requires current permission. Once shared, a record cannot be changed to Personal. If you need a Personal replacement, create it explicitly and remove the shared record only when you have permission and have considered its history and relationships.

## What a page or integration can access

Menus and published pages select presentation. Record reads, edits, removals, files, exports, search and AI each enforce the current user’s relevant permissions. The same contract applies to Developer API, MCP and automation access. A URL, record ID, app ID or organization ID identifies a target; it does not grant authority.

## If saving fails

For missing scope, choose an eligible explicit value. For permission denied, refresh your available choices or contact an administrator. For a stale-write conflict, reload the current record and review the other changes before saving again. Keep your unsaved text if possible; do not repeatedly submit a consequential action. Share the safe error code and correlation reference with support.

---

Capability review: 2026-10-23. [View the canonical guide](https://support.buildwithhq.com/getting-started/record-visibility.html).

---
title: "What makes BuildWithHQ different"
section: "Getting Started"
canonical_url: "https://support.buildwithhq.com/getting-started/what-makes-it-different.html"
reviewed_at: "2026-09-14"
authority: Official
---

# What makes BuildWithHQ different

Seven differences you could verify in the database schema — and what each one means for your day.

## In brief

- **The claim:** Every difference here is structural, not a setting
- **Audience:** Anyone evaluating the platform
- **Format:** What it is → why your life is easier

Every app-builder platform says it's secure, flexible, and AI-powered. So this page makes a different kind of argument: each difference below is a **structural property of how the platform is built** — something an auditor could verify by reading the database schema, not a policy that depends on everyone remembering to follow it. For each one: what it is, and what it does for the people using it.

## 1. Every application gets its own databases — three of them

Most platforms put all customers in shared tables and separate them with a filter column. Here, every application you create is provisioned with three physically separate databases: live data, immutable history, and AI. Each carries its own identity, and a built-in tripwire refuses to serve traffic if a connection ever points at the wrong database — misrouting fails loudly instead of leaking quietly.

**What this means:** database routing separates SaaS applications. Customer organizations inside an application still share that application's databases, with server-enforced account, DataRole, Location, and record permissions. Separate databases help with operational boundaries, but shared hardware still needs capacity planning.

## 2. One security layer, inherited by everything

Everything in an application — contacts, tasks, conversations, files, events — is anchored to a single universal record identity, and every read flows through one security layer that evaluates role, location scope, and capability. Features don't implement their own access checks; they inherit the one model. The [inbox](../builder-guide/universal-inbox.html)  has no inbox security code. [AI insights](../first-class-modules/ai-insights.html)  inherit visibility from their source records. Even a user's [favorites](../end-user/whats-new-and-favorites.html)  silently drop a record the moment access is revoked — the bookmark reads through the same layer as everything else.

**Easier because:** builders configure permissions once and every feature — including ones that ship next year — obeys them. There is no per-feature permission matrix to keep synchronized, and no new feature can introduce a new class of leak, because no feature has an access path of its own.

## 3. Security decisions you can replay

The permission tables keep full version history, and every AI data retrieval logs a cryptographic proof of exactly what the user was allowed to see at that instant — into a per-tenant, hash-chained record that can't be silently edited. Any past access can be [replayed](../trust/authorization-replay.html): re-derived under the rules as they stood then, or under today's rules, and compared against the proof.

**Easier because:** when a customer or auditor asks “did the AI ever see something it shouldn't have?”, the answer is a procedure with a verdict, not a promise. No other builder platform we're aware of can rewind a security decision and check it.

## 4. Encryption that changes what's physically possible

Fields marked [secure](../builder-guide/secure-fields.html)  are encrypted with per-tenant keys — and the database itself enforces, by constraint, that a field value holds *either* readable text *or* an encrypted envelope, never both. Search indexing and AI read only the readable side, so an encrypted value isn't “filtered out” of search and AI — **it was never there to filter**.

**Easier because:** protecting a sensitive field is one checkbox with no follow-up checklist. There is no list of downstream features someone must remember to exclude it from, because the exclusion is a property of storage, not of each feature's good behavior.

## 5. Customize everything — and still receive upgrades

Template platforms force a choice: stay stock and get updates, or customize and be stranded. Here every block on every page carries a stable identity, forks record the exact baseline they diverged from, and [upgrades arrive as block-by-block choices](../builder-guide/templates-forking.html)  merged three ways against your customizations — with conflicting blocks flagged for a human decision instead of silently overwritten. Premium bespoke work is excluded from automated upgrades entirely, by classification.

**Easier because:** builders customize on day one without mortgaging every future improvement, and tenants can restyle their own pages knowing an upstream release will never flatten their changes.

## 6. AI that was designed inside the rules, not bolted on after

The permission model has an AI-specific read capability as a first-class flag — meaning a role can see data itself while excluding that data from AI entirely. On top of that sit the rest of the controls this documentation covers: [assistants that propose while humans approve](../builder-guide/goclaw-in-depth.html), action budgets enforced by the platform rather than the AI's own logic, full attribution on everything AI produces, and [scored Harness Pack gates](../builder-guide/harness-packs.html)  before an AI behavior serves customers.

**Easier because:** you can adopt AI feature by feature, user by user, with the same governance answer every time — instead of choosing between “no AI” and “trust the AI.” And when AI runs on partner or dedicated hardware, the data rules travel with it, because they live in the platform, not the model.

## 7. A history that can prove itself

Every application's audit trail is [append-only and hash-chained](../trust/tenant-logging.html)  — tampering is detectable by arithmetic, not just forbidden by policy. Third-party [extensions](../builder-guide/appliances-and-endpoints.html)  operate under manifests frozen at release, with every network attempt logged as allowed or blocked and every data access written to a tenant-verifiable disclosure ledger. An active organization owner can also configure [export of selected log metadata to their own Snowflake account](../builder-guide/snowflake-analytics-sync.html). Builder support requires explicit Snowflake scopes and a credential bound to that organization's active owner; it does not grant access to other organizations. Export requires connection verification and explicit enablement.

**Easier because:** disputes end with evidence, security questionnaires get short answers, and tenants get warehouse-scale analytics over their own history without their data ever becoming someone else's dataset — a data-ownership answer most platforms can't give.

To pressure-test these claims — ours and anyone's — take the [ten questions](ten-questions.html)  into your next vendor evaluation.

## The same differences, from each chair

| Structural difference | For the builder | For the tenant |
| --- | --- | --- |
| Dedicated database triplet | No noisy neighbors; clean compliance answers | Their data is physically theirs |
| One inherited security layer | Configure once; every feature obeys | Consistent visibility everywhere, no surprises |
| Replayable authorization | Auditor questions become queries | Provable answers about their own data |
| Constraint-enforced encryption | One checkbox, zero follow-up checklist | Sensitive values can't leak into search or AI |
| Fork-and-merge templates | Ship improvements without breaking customers | Customize freely, still receive updates |
| AI inside the permission model | Adopt AI incrementally with one governance story | An assistant that helps but never acts alone |
| Self-proving history | Disputes end with evidence; questionnaires get short answers | Their own history, exportable to their own warehouse |

Note

The honest framing for competitive conversations: no single item above is unique to this platform in isolation — field encryption exists elsewhere, and so do audit logs. What's different is that all of them are structural and all of them compose, in one platform built for people who resell software to their own customers. The integration is the moat.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/getting-started/what-makes-it-different.html).

---
title: "Ten questions to ask any platform (including us)"
section: "Getting Started"
canonical_url: "https://support.buildwithhq.com/getting-started/ten-questions.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Ten questions to ask any platform (including us)

Take these into every vendor evaluation. Our answers are below, each linked to its documentation. We suggest asking everyone else for theirs in writing.

## In brief

- **Format:** Question → why it matters → our answer, with the doc link
- **Use it on:** Every platform you evaluate
- **Our answers:** All ten are “yes,” in writing, below

Platform demos all look the same. The differences live in questions that only come up later — during the audit, the incident, the migration, the customer's security review. Here are ten worth asking *before* you commit, with our answers. Each answer links to the documentation that backs it, because an answer you can't verify is a slogan.

## 1. “If we order you to delete our audit trail, will your system refuse?”

*Why it matters:* the moment an audit trail can be deleted on request — by you, by an admin, by a compromised account — it stops being evidence.

*Our answer:* yes, it refuses. The retention cleanup routine has the compliance-critical history tables — the audit log and every record- and field-level change and access log — hard-excluded at the code level. Asking it to delete them doesn't get a warning; it gets an error. The same discipline runs through the page system: the pruner that trims editing history is written to never delete the record of what was published. [Tenant logging](../trust/tenant-logging.html).

## 2. “Can you prove — not promise — that your AI never accessed something it shouldn't have?”

*Why it matters:* every platform will promise this. Almost none can demonstrate it for a specific query on a specific day last quarter.

*Our answer:* every AI retrieval logs a cryptographic proof of exactly what that user was permitted to see at that instant, into a tamper-evident chain — and the permission rules themselves keep full version history, so any past decision can be replayed and given a verdict. “As of then” catches violations; “as of now” catches drift. [Replayable authorization](../trust/authorization-replay.html).

## 3. “Does your access log distinguish an AI reading a field from a human viewing it?”

*Why it matters:* “who saw this?” and “did an AI ingest this?” are different questions with different regulatory weight, and a log that can't tell them apart can't answer either.

*Our answer:* yes — field-level access logging records the *kind* of access: a human view, an export, a print, an API read, a report read, or an AI read, each its own category. Down to the individual field. [Tenant logging](../trust/tenant-logging.html).

## 4. “What happens if a connection ever points at the wrong customer's database?”

*Why it matters:* on shared-table platforms this question doesn't even parse — there is only one database, and isolation is a WHERE clause. Where separate databases exist, misrouting is the nightmare scenario.

*Our answer:* every tenant database knows its own identity, and a tripwire check refuses to serve a connection whose claimed identity doesn't match — the request fails loudly with a misconnection error naming both sides, instead of quietly serving someone else's data. [The isolation model](what-makes-it-different.html).

## 5. “If we encrypt a field, list every feature we must remember to exclude it from.”

*Why it matters:* the usual answer is a checklist — search, reports, AI, exports, integrations — and the checklist is exactly where breaches live, because someone forgets one.

*Our answer:* the list is empty. A database constraint makes it physically impossible for a secure field to hold readable text alongside its encrypted envelope, and search and AI only ever consume the readable side. Nothing downstream needs to exclude it, because there is nothing to exclude. [Secure fields](../builder-guide/secure-fields.html).

## 6. “Show us every customized page with an upstream update waiting — right now.”

*Why it matters:* template platforms lose track of forks. The honest competitor answer is “customers find out when something looks broken.”

*Our answer:* one query. Every fork records the exact version it diverged from, so the platform can enumerate, at any moment, every customized page whose baseline is behind the current release — with the original, the customization, and the new version side by side, ready for a block-level merge that flags conflicts instead of overwriting. [Templates, forks, and upgrades](../builder-guide/templates-forking.html).

## 7. “When our AI assistant hits its daily limit, whose code enforces it?”

*Why it matters:* if the answer is “the AI is instructed to stop,” the limit is a suggestion. Instructions are what misbehaving software ignores first.

*Our answer:* the platform's, at the moment each action is queued — outside the assistant entirely. A hypothetically malfunctioning assistant is still mechanically capped, and everything it wants to do waits in a human approval queue besides. [GoClaw in depth](../builder-guide/goclaw-in-depth.html).

## 8. “Can someone probe your API to learn which accounts and apps exist?”

*Why it matters:* APIs that answer “not yours” differently from “doesn't exist” are enumeration oracles — reconnaissance tools handed to attackers for free.

*Our answer:* no. Routing and lookup paths deliberately return the same nothing for “not yours” and “not real,” a design rule written into the code as a comment future engineers can't miss. [API overview](../api/overview.html).

## 9. “Can our customers take everything and leave?”

*Why it matters:* the platforms most eager to hold your data are the ones you most need an exit from. Data ownership you can't exercise isn't ownership.

*Our answer:* yes — an authorized account export provides that organization's records and related artifacts with checksums. A whole-SaaS backup is separate and may contain multiple organizations; it is not an individual organization's export. It is a standing owner-only feature available at any time, not an off-boarding concession ([Back up and download your data](../end-user/download-your-data.html) ). Builders can separately export the versioned JSON and JSON Schema definitions for pages and workflows. Customer-owned S3 restore bundles can preserve the database, files, schemas, settings, manifest, and checksums outside BuildWithHQ. For an enterprise relocation or a company shutdown, the application can run in AWS, Azure, another cloud environment, or a virtual machine using the continuity runtime. [Business continuity and application portability](../trust/business-continuity-and-portability.html).

## 10. “When third-party code touches our data, can you show us exactly what ran?”

*Why it matters:* “an integration accessed your data” is not an answer. *Which version, doing what, reaching where* is an answer.

*Our answer:* extensions run under manifests frozen and fingerprinted at release — endpoints, network reach, everything. Every data access lands in a tamper-evident ledger with that fingerprint attached; every network attempt is logged as allowed or blocked, host and port included. The audit trail names the exact code. [Appliances and their endpoints](../builder-guide/appliances-and-endpoints.html).

---

Note

Every answer above is documented on this public site — no NDA, no sales call, no “let me check with engineering.” We'd suggest asking the same ten questions of any platform you're evaluating, and asking for the answers in writing. The ones who can answer will be glad you asked.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/getting-started/ten-questions.html).

---
title: "Create your account"
section: "Getting Started"
canonical_url: "https://support.buildwithhq.com/getting-started/create-your-account.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Create your account

Sign up, verify your email, and secure your account before creating anything.

## In brief

- **Audience:** New builders
- **Time:** 5 min
- **You'll need:** A work email

Your builder account is the owner of everything you create, so a couple of setup steps are required before the platform lets you build.

## Sign up and verify your email

Create your account with your email address and a strong password. A verification link is sent immediately — **you must verify your email before you can create an application or invite teammates**. This is a hard requirement, not a reminder.

## Protect the account

Turn on two-factor authentication under account security. You'll scan a QR code with any authenticator app and receive a set of recovery codes — store those somewhere safe; each one works exactly once.

Important

After 10 failed sign-in attempts within 15 minutes, sign-in is locked for 15 minutes. This protects your account and cannot be lifted early by support.

## Trials and activation

New accounts start on a trial. When a trial ends, the platform enforces it automatically — you'll be prompted to choose a plan to continue. See [Plans and trials](../billing/plans-and-trials.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/getting-started/create-your-account.html).

---
title: "Launch your first app"
section: "Getting Started"
canonical_url: "https://support.buildwithhq.com/getting-started/your-first-app.html"
reviewed_at: "2026-10-22"
authority: Official
---

# Launch your first app

Create an application and understand what gets provisioned when you do.

## In brief

- **Audience:** New builders
- **Time:** 10 min
- **Requires:** Verified email

Creating an application starts a staged provisioning operation. Follow the app’s provisioning status until it reports readiness. If setup is pending or fails, review the safe error and correlation reference before retrying; do not create duplicate apps to work around a failed stage.

## What gets created

- **Your application record** and the default web address configured for it. Open the app after provisioning and routing are ready.
- **Three dedicated databases** — live data, audit history, and AI — reserved for this application alone.
- **Storage and AI allowances** for the app, metered against your plan.
- **You as the owner**, with full administrative rights over the new app.

## Two ways to start

**Start from a template** — pick a template pack and get a complete, working application (pages, menus, user types) that you then customize. This is the fastest path and the one we recommend for a first app.

**Build with AI** — describe the product you want in a guided interview, and the platform drafts the application structure for you. See [Build with AI](../builder-guide/build-with-ai.html).

Tip

You can create additional apps later from the same account — each one gets its own isolated databases and its own domain setup.

## Standard and dedicated runtime

Database routing and service compute are separate concerns. Confirm the app’s configured runtime and enabled workers before depending on background processing. Optional dedicated compute or customer-hosted Appliance operation requires its own deployment setup and agreed commercial terms; creating an app does not provision that compute automatically.

---

Capability review: 2026-10-22. [View the canonical guide](https://support.buildwithhq.com/getting-started/your-first-app.html).

---
title: "Manage customer organizations"
section: "Getting Started"
canonical_url: "https://support.buildwithhq.com/getting-started/manage-customer-organizations.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Manage customer organizations

Create and administer every customer organization inside one SaaS app.

## In brief

- **Audience:** SaaS builders
- **Workspace:** SaaS Apps > Organizations
- **Scope:** One selected app

Open a SaaS app and choose **Organizations** to manage the customer accounts hosted by that product. The directory is limited to the selected app and shows each organization’s owner, status, user count, DataRole count, and Location count.

## Create an organization

Choose **New organization** and enter the customer identity plus its initial owner. API-driven signup can include up to five initial DataRoles and five initial Locations in the same submission; the console provides the first role/location fields and supports adding the rest after creation. The account, owner, owner authority, roles, and locations are committed together; an invalid part leaves no half-created organization.

A builder-owned marketing site can create the same organization through the Developer API after its own signup service verifies the owner. The browser posts to the builder's backend; that backend keeps the app credential private and calls `POST /v1/apps/{saasAppId}/accounts`. API-created organizations appear in this directory without importing or synchronizing them, and the new owner can use the same account administration workspace inside the SaaS. Follow [How customer organizations can signup from your website](../api/customer-organization-website-signup.html)  for the complete implementation.

## Manage the account

- Rename the organization, change its primary email, or deactivate/reactivate it with revision protection.
- Add external tenant users and edit or deactivate existing users.
- Create, edit, and safely deactivate DataRoles and Locations.
- Assign each user the allowed DataRoles and either all Locations or a selected Location set.

Before adding ordinary users, enable at least one shared User Type for tenant assignment in the app’s presentation policy. The account-local **owner** type is reserved for the initial owner and cannot be assigned to ordinary users.

Note

Organization IDs select a record; they do not prove authority. The server verifies the signed-in builder, selected app ownership, registered database route, SaaS identity, and AppAccount scope on every request. Browsers never receive database names or connection strings.

Tip

Deactivate accounts, users, DataRoles, or Locations when history must be retained. Hard deletion is intentionally not the normal administrative lifecycle.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/getting-started/manage-customer-organizations.html).

---
title: "Connect a custom domain"
section: "Getting Started"
canonical_url: "https://support.buildwithhq.com/getting-started/custom-domains.html"
reviewed_at: "2026-10-22"
authority: Official
---

# Connect a custom domain

Point your own domain at your application and get automatic TLS.

## In brief

- **Audience:** Builders
- **Time:** 15 min + DNS propagation
- **Requires:** Access to your DNS

After provisioning and routing are ready, connect your own domain using the DNS values shown by the console. Wait for domain verification and certificate readiness before inviting customers. A saved hostname is not proof that HTTPS is ready.

## Add the domain

1. In the app's settings, open **Domains** and add the hostname you want (for example `app.yourcompany.com`).
2. The console shows you a DNS record to create at your DNS provider — copy it exactly.
3. Create the record, then return and click **Verify**. Verification usually completes within minutes, but DNS changes can take up to 24–48 hours to propagate depending on your provider.

## Common problems

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Verification never completes | Record created at the wrong host, or a conflicting existing record | Check for typos in the host name; remove any old A/CNAME records on the same host |
| Certificate warning in the browser | DNS still propagating | Wait for propagation to finish; certificates issue automatically once verification passes |
| Domain works but shows another site | DNS points somewhere else (old hosting) | Confirm the record target matches what the console shows exactly |

Each customer-facing app can carry multiple hostnames, so staging and production addresses can coexist on one app.

---

Capability review: 2026-10-22. [View the canonical guide](https://support.buildwithhq.com/getting-started/custom-domains.html).

---
title: "Invite your team"
section: "Getting Started"
canonical_url: "https://support.buildwithhq.com/getting-started/team-and-roles.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Invite your team

Add teammates to the builder console and control what they can do.

## In brief

- **Audience:** Builder owners
- **Time:** 5 min
- **Requires:** Verified email

You don't have to build alone. Teammates get their own sign-in to the builder console and act with their own identity — never share credentials.

## Invitations

Invite a teammate by email from your account's team page. They receive a one-time invitation link, create their own password, and appear in your team list. Invitations require your account email to be verified first.

## Roles

The account has one **Owner** — the person who created it — plus team members with assigned permission roles. Owners control billing, can delete applications, and manage the team itself.

Tip

Everything a teammate does is recorded in the audit history under their own identity, which matters when you need to answer “who changed this?” later.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/getting-started/team-and-roles.html).

---
title: "A tour of the three consoles"
section: "Getting Started"
canonical_url: "https://support.buildwithhq.com/getting-started/platform-tour.html"
reviewed_at: "2026-09-14"
authority: Official
---

# A tour of the three consoles

Choose the Admin, Developer, or Operations workspace without changing identity or permissions.

## In brief

- **Audience:** New builders
- **Reading time:** 6 min
- **Format:** Orientation

BuildWithHQ groups work into three focused consoles. They reuse the same login, session, APIs, and authorization; this split changes navigation, not what your identity is allowed to do.

## Choose by job

| Console | What lives there | Covered in |
| --- | --- | --- |
| **Admin** | Team, billing, account settings, branding, communications, security, and audit. | [Admin Console guide](../console-guides/admin-console.html)  |
| **Developer** | SaaS apps, templates, harnesses, appliances, marketplace, API clients, and integrations. | [Developer Console guide](../console-guides/developer-console.html)  |
| **Operations** | Provisioning, analytics, backups, domains, logs, storage, and AI operations. | [Operations Console guide](../console-guides/operations-console.html)  |

Note

Navigation location is not authorization. Every backend request still enforces the existing account, app, role, DataRole, location, and capability rules.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/getting-started/platform-tour.html).

---

# Section: Console Guides

---
title: "Three consoles, one BuildWithHQ identity"
section: "Console Guides"
canonical_url: "https://support.buildwithhq.com/console-guides/overview.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Three consoles, one BuildWithHQ identity

How Admin, Developer, and Operations divide navigation without dividing authentication or authorization.

## In brief

- **Login:** Shared
- **Sessions:** Shared
- **Permissions:** Existing server rules

BuildWithHQ separates the builder experience into three focused consoles. This is a **navigation and design split**: your login, session, account membership, app ownership, roles, DataRoles, locations, and server permissions remain the same.

| Console | Primary job | Production home |
| --- | --- | --- |
| **Admin Console** | People, billing, branding, communications, security, and account governance. | [hello.buildwithhq.com](https://hello.buildwithhq.com/dashboard)  |
| **Developer Console** | SaaS apps, templates, AI harnesses, appliances, integrations, API clients, and marketplace publishing. | [dev.buildwithhq.com](https://dev.buildwithhq.com/dashboard)  |
| **Operations Console** | Provisioning, runtime health, domains, backups, logs, analytics, storage, and AI operations. | [ops.buildwithhq.com](https://ops.buildwithhq.com/dashboard)  |

## What stays shared

- the same sign-in, MFA, recovery, invitation, and account-selection flow;
- the same browser session and account/app context;
- the same backend APIs and stored-procedure-backed application services;
- the same authorization checks on every request; and
- the same audit and correlation evidence.

## Navigation is not permission

A link appearing in a console does not grant access, and hiding a link is not a security boundary. Each service verifies the signed-in identity, account/app relationship, and required capability server-side.

Note

You may use all three consoles with the same identity. What you can view or change remains limited by the permissions already assigned to you.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/console-guides/overview.html).

---
title: "Admin Console guide"
section: "Console Guides"
canonical_url: "https://support.buildwithhq.com/console-guides/admin-console.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Admin Console guide

Manage the business and governance layer behind every SaaS app from hello.buildwithhq.com.

## In brief

- **Home:** hello.buildwithhq.com
- **Focus:** Account governance
- **Local preview:** localhost:4173

Use the Admin Console for account-wide responsibilities. It intentionally keeps app building and runtime operations out of the main navigation so owners can focus on people, money, brand, and governance.

[Open Admin Console](https://hello.buildwithhq.com/dashboard) [Team](https://hello.buildwithhq.com/team) [Billing](https://hello.buildwithhq.com/billing) [Security](https://hello.buildwithhq.com/security)

## Primary workspaces

| Workspace | Use it for | Related guide |
| --- | --- | --- |
| [Dashboard](https://hello.buildwithhq.com/dashboard)  | Account status and the work requiring administrative attention. | [Getting Started](../getting-started/index.html)  |
| [Team](https://hello.buildwithhq.com/team)  | Members, invitations, existing roles, status, and ownership transfer. | [Team and roles](../getting-started/team-and-roles.html)  |
| [Billing](https://hello.buildwithhq.com/billing)  | Plans, invoices, payment status, storage/resources, and account lifecycle. | [Billing & Account](../billing/index.html)  |
| [Branding & communications](https://hello.buildwithhq.com/branding)  | White-label identity and account communication settings. | [White-label guidance](../end-user/for-builders-white-label.html)  |
| [Security & audit](https://hello.buildwithhq.com/security)  | MFA, sessions, security posture, and accountable change history. | [Trust & Security](../trust/index.html)  |

## When to switch consoles

Move to Developer when you need to change the product or publish an artifact. Move to Operations when you need to diagnose or operate a running app. Cross-console links preserve the intended destination; they do not elevate permission.

Tip

Keep account-owner and billing work in the Admin Console even when the affected resource is an app. That makes governance responsibilities easier to find and audit.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/console-guides/admin-console.html).

---
title: "Developer Console guide"
section: "Console Guides"
canonical_url: "https://support.buildwithhq.com/console-guides/developer-console.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Developer Console guide

Build apps, publish exact versions, configure integrations, and use the developer platform from dev.buildwithhq.com.

## In brief

- **Home:** dev.buildwithhq.com
- **Focus:** Build and extend
- **Local preview:** localhost:4175

Use the Developer Console for the product definition and its reusable artifacts. It combines visual building with the developer escape hatches needed for APIs, installed services, AI, and exact-version distribution.

[Open Developer Console](https://dev.buildwithhq.com/dashboard) [SaaS Apps](https://dev.buildwithhq.com/apps) [Templates](https://dev.buildwithhq.com/templates) [AI Harnesses](https://dev.buildwithhq.com/templates/harnesses) [Appliances](https://dev.buildwithhq.com/appliances) [Marketplace](https://dev.buildwithhq.com/marketplace)

## Primary workspaces

- **[SaaS Apps](https://dev.buildwithhq.com/apps) ** — create products, inspect app-bound identity, manage API clients, and configure integrations.
- **[Templates](https://dev.buildwithhq.com/templates) ** — author, validate, version, publish, install, and upgrade reusable template content.
- **[AI Harnesses](https://dev.buildwithhq.com/templates/harnesses) ** — compose harness packs, queue exact-version evaluations, publish only passed artifacts, and inspect aggregate installations.
- **[Appliances](https://dev.buildwithhq.com/appliances) ** — package isolated services, declare endpoints/egress, validate releases, and publish exact versions.
- **[Marketplace](https://dev.buildwithhq.com/marketplace) ** — discover entitled versions, install products, and manage the seller catalog, offers, artifacts, revenue, and payouts.
- **[Developer Platform](../api/index.html) ** — use REST, webhooks, connectors, MCP, the CLI, logs, AI, and versioned OpenAPI contracts.

## Customer organizations

Inside a selected SaaS app, use **Organizations** to create and administer that product’s customer accounts, tenant users, DataRoles, and Locations. See [Manage customer organizations](../getting-started/manage-customer-organizations.html)  for the complete lifecycle and security boundary.

## Recommended starting path

1. Read [Launch your first app](../getting-started/your-first-app.html).
2. Use the [Builder Guide](../builder-guide/index.html)  for product authoring.
3. Follow the [Developer API quickstart](../api/quickstart.html)  before writing an integration.
4. Review [Selling Templates](../selling/index.html)  before publishing marketplace products.

The Developer Console builds with React components, validated data bindings, reviewed APIs, and declared package or connector contracts. Platform-managed tables, database routes, provider secrets, and tenant infrastructure are not editor surfaces.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/console-guides/developer-console.html).

---
title: "Operations Console guide"
section: "Console Guides"
canonical_url: "https://support.buildwithhq.com/console-guides/operations-console.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Operations Console guide

Operate running SaaS workloads with bounded health, provisioning, backup, domain, log, analytics, and AI evidence.

## In brief

- **Home:** ops.buildwithhq.com
- **Focus:** Operate with evidence
- **Local preview:** localhost:4176

Use the Operations Console after an app exists. Its job is to show bounded deployment and runtime evidence through supported operational APIs.

[Open Operations Console](https://ops.buildwithhq.com/dashboard) [SaaS Operations](https://ops.buildwithhq.com/apps) [AI Operations](https://ops.buildwithhq.com/operations/ai)

## Primary workspaces

- **[Provisioning & deployment](https://ops.buildwithhq.com/apps) ** — current job state, retries, compensation, and logical target evidence. Select the app, then open Provisioning.
- **[Analytics](https://ops.buildwithhq.com/apps) ** — app-level usage and operational trends available to the signed-in identity. Select the app, then open Analytics.
- **[Backups](https://ops.buildwithhq.com/apps) ** — recovery points and configured destinations without exposing storage credentials. Select the app, then open Backups.
- **[Domains](https://ops.buildwithhq.com/apps) ** — hostname, verification, certificate, and routing status. Select the app, then open Domains.
- **[Logs & errors](https://ops.buildwithhq.com/apps) ** — bounded diagnostics and correlation tracing. Select the app, then open Logs.
- **[Resources & storage](https://ops.buildwithhq.com/apps) ** — entitled and consumed capacity without direct host access. Select the app, then open Resources.
- **[AI Operations](https://ops.buildwithhq.com/operations/ai) ** — endpoint health, queue/fleet state, rebuild jobs, and safe failure evidence.

## Operate through reviewed actions

Retries and recovery actions are available only through reviewed operations that enforce current expected state, lease/version fences, authorization, and correlation IDs.

## Incident handoff

Start with the app, component, time window, and correlation ID. Link the relevant bounded evidence and record the approved action taken. For developer-facing log use, see [Logs, diagnostics, and correlation tracing](../api/logs-and-observability.html).

Tip

The Operations Console answers ‘what is running and what needs attention?’ Product definition belongs in Developer; account policy belongs in Admin.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/console-guides/operations-console.html).

---

# Section: How-To Do This

---
title: "How to build CrewOS"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/crewos.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build CrewOS

Build a governed team of specialized AI operators with shared records, approval boundaries, and replayable execution evidence.

## In brief

- **Pattern:** AI agent workforce
- **First release:** One agent, one approved action
- **Build surface:** Developer Console

**CrewOS** follows the **AI agent workforce** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/crewos.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

CrewOS is now implemented and live-proven as the first product-specific Build This production solution. Its governed team roster, three managed record families, six published pages, favorites, secured file attachments, relationships, activity, approval boundaries, and deactivation lifecycle were exercised against a route-resolved disposable tenant and render-checked on desktop and mobile. It is not yet a Template Library listing; exact-version template packaging is intentionally later work.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Give each agent a narrow job, permitted context, declared tools, and a measurable handoff. The product is successful when a person can see what the agent learned, approve or refuse its proposed work, and reconstruct what happened afterward.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Agent profile** | Role, instructions, enabled tools, authority ceiling, owner, and active version. |
| **Work request** | Goal, requester, priority, source record, current state, and due time. |
| **Suggestion batch** | The plan produced from one activity version and its supporting context. |
| **Action suggestion** | A proposed narrow operation, inputs, risk, evidence, and approval state. |
| **Action execution** | The authorized operation, executor, result, correlation ID, and failure evidence. |
| **Rating** | Human outcome, quality score, correction, and reusable feedback. |

**Relationship rule:** Relate every request to its source business records; keep suggestions, approvals, executions, and ratings as an unbroken chain.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Mission control with agent availability and bounded queue health.
- Work-request detail with source context and plan.
- Approval queue showing evidence, risk, and exact proposed changes.
- Execution timeline and failure evidence.
- Ratings and outcome review by agent/version.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Separate who may request work, inspect context, approve an action, and operate agents.
- Apply the source record's normal DataRole, field, and location rules to agent context.
- Set explicit authority ceilings for customer-facing, financial, destructive, and external actions.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Request → read-only planning → suggestion batch.
- Suggestion → policy check → approval or refusal.
- Approved suggestion → deterministic queued execution → recorded result.
- Material source activity change → mark the old plan stale and require preparation again.
- Completed work → human rating → versioned improvement input.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Expose only declared, action-specific APIs as agent tools.
- Route external calls through managed connections or appliance endpoints.
- Send approval and failure attention to Universal Inbox without moving the source record into the inbox.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Use GoClaw as the planner/worker and the canonical suggestion/execution contracts as the boundary between reasoning and mutations. Agent memory may assist retrieval, but it does not replace application records or authorization.

- Start with read-only retrieval against one record family.
- Require structured suggestions with evidence and expected current state.
- Preserve the Inbox `ActivityVersion` fence through preparation, approval, and execution.
- Evaluate exact harness/agent versions and retain ratings by version.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** A research agent reads one permitted account, prepares a follow-up task, and an authorized person approves task creation. A changed source activity invalidates the pending suggestion.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Prove an unauthorized agent cannot retrieve the record.
- Prove refused and stale suggestions cannot execute.
- Retry execution without producing duplicate work.
- Trace request, approval, tool call, and result by correlation ID.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

A useful first agent removes one recurring preparation step. Add more roles only after its permissions, approvals, and outcome measurements are trustworthy.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/crewos.html).

---
title: "How to build SignalIQ"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/signaliq.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build SignalIQ

Build account signals, explainable scoring, deal-risk views, and approved next-best actions over connected revenue records.

## In brief

- **Pattern:** AI sales intelligence
- **First release:** One signal-to-action loop
- **Build surface:** Developer Console

**SignalIQ** follows the **AI sales intelligence** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/signaliq.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

SignalIQ is now implemented and live-proven as a production Build This solution. Six managed record families cover accounts, contacts, opportunities, signals, versioned score snapshots, and evidence-backed recommendations across five professional pages. Every managed record uses the current secured create, view, edit, remove, favorite, relation, file, and activity contracts. AI Insights remain a permission-aware derived feed, recommendations retain evidence and model/score versions, and material actions stay behind the current policy or human-approval boundary. The complete routed API journey and desktop/mobile Chromium experience passed against a disposable tenant. SignalIQ is not yet a Template Library listing; exact-version packaging remains later work.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Turn scattered account changes into a prioritized queue that tells a seller what changed, why it matters, which evidence supports it, and what action is safe to take next.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Account** | Company identity, segment, owner, health, and commercial context. |
| **Contact** | People, roles, consent, engagement, and account relationship. |
| **Opportunity** | Stage, value, probability, close date, owner, and competing context. |
| **Signal** | Typed product, intent, engagement, support, or external event with observed time. |
| **Score snapshot** | Versioned score, factors, weights, confidence, and calculation time. |
| **Recommendation** | Suggested next action, evidence, owner, state, and expiry. |

**Relationship rule:** Connect signals and recommendations to the exact account, contacts, opportunities, activities, and source events that explain them.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Ranked account and opportunity command center.
- Account 360 with activity, signals, pipeline, and support history.
- Signal feed with filters and evidence drill-down.
- Recommendation queue with owner and expiry.
- Scoring configuration and version comparison.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Scope sellers to assigned or permitted accounts; give leaders only the rollups they are authorized to see.
- Protect sensitive commercial fields separately from general account access.
- Require approval for outbound contact or CRM mutation when policy calls for it.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Inbound event → normalize → deduplicate → relate to account.
- Material signal → recompute versioned score.
- Threshold crossing → create explainable recommendation and notify owner.
- Approved recommendation → task, stage change, or connector action.
- Expired or contradicted evidence → close or replace recommendation.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Ingest CRM, product usage, intent, support, and engagement events through APIs or webhooks.
- Send approved actions to CRM, email, calendar, or sales tools.
- Retain source-system identifiers and idempotency keys for reconciliation.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Use AI to summarize permitted account context and propose recommendations, while deterministic rules retain responsibility for required fields, thresholds, ownership, and safe execution.

- Build retrieval from connected account records and approved knowledge.
- Store the evidence and score/model version behind every recommendation.
- Show confidence and missing context instead of manufacturing certainty.
- Evaluate whether recommendations improve accepted actions and outcomes.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Ingest one product-usage signal, update one account score, show the evidence on the account page, and let the owner approve creation of a follow-up task.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Replay duplicate signals without duplicating recommendations.
- Prove account/field restrictions apply to scoring evidence and AI context.
- Test score-version changes against a fixed fixture.
- Trace a recommendation back to every source event.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Rank only the decision your first users actually make. One credible queue beats a broad score nobody can explain.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/signaliq.html).

---
title: "How to build Resolve"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/resolve.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build Resolve

Build a permission-aware support operation that identifies customers, retrieves policy, proposes safe resolutions, and escalates exceptions.

## In brief

- **Pattern:** AI customer support
- **First release:** One issue, one safe resolution
- **Build surface:** Developer Console

**Resolve** follows the **AI customer support** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/resolve.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

Resolve is now implemented and live-proven as a production Build This solution. Native Conversations own communication lifecycle, Universal Inbox remains the attention layer, and Knowledge Core owns versioned policy evidence. Four managed record families cover customer context, issues, resolution suggestions, and escalations across five professional responsive workspaces. Current secured APIs and stored procedures provide create, view, edit, remove, favorite/unfavorite, relationships, files, and activity. Cited AI findings remain permission-aware, and customer-facing or material work stays behind the current policy or human-approval boundary with the Inbox ActivityVersion fence. Golden/disposable SQL parity, the routed product journey, and desktop/mobile Chromium proof passed. Resolve is not yet a Template Library listing; exact-version packaging remains later work.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Help support teams understand an incoming request, see verified customer context and policy evidence, and complete a narrow resolution without giving an AI or browser broad authority.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Conversation** | The native customer communication and message history. |
| **Customer context** | Permitted contacts, orders, subscriptions, invoices, and entitlements. |
| **Issue** | Intent, category, urgency, owner, SLA, status, and related conversation. |
| **Policy source** | Versioned support policy, product guidance, and effective dates. |
| **Resolution suggestion** | Proposed reply/action, evidence, confidence, and approval state. |
| **Escalation** | Reason, queue, assignee, severity, and handoff evidence. |

**Relationship rule:** Keep conversations and business records in their native models; use Universal Inbox as the attention layer that points to the work requiring action.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Team support inbox and SLA queue.
- Conversation workspace with customer and order context.
- Policy evidence viewer.
- Resolution approval panel.
- Escalation and quality-review queues.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Limit customer/order context to the signed-in support role and location.
- Protect payment, identity, health, or other sensitive fields independently.
- Set action-specific ceilings for credits, cancellation, access reset, and data changes.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Message received → identity match or safe manual resolution.
- Issue classification → queue, owner, SLA, and required context.
- Suggestion → policy and confidence check → approval when required.
- Approved narrow action → execute once → reply and timeline evidence.
- Missing authority or ambiguous identity → escalation, never guessed mutation.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Connect approved email, SMS, and form channels.
- Retrieve order, billing, entitlement, or delivery context through reviewed connectors.
- Expose separate narrow actions for each supported resolution instead of a general mutation endpoint.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Use retrieval to ground answers in effective policy and permitted customer records. AI may prepare a reply or resolution action, but policy and authorization decide whether it can run.

- Ingest policy with source/version metadata and visual evidence where needed.
- Return citations/evidence with every suggested answer.
- Represent refunds, resets, cancellations, and escalations as separate action contracts.
- Log retrieval, refusal, approval, and exact result.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Receive one email category, match it to a customer, retrieve one policy, prepare a reply and a bounded action, and require approval before execution.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Test unknown and ambiguous customer identity.
- Test expired policy and insufficient evidence.
- Prove refund/permission ceilings cannot be bypassed.
- Replay inbound messages and actions without duplicate side effects.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Begin with a frequent, reversible issue whose policy is clear. Earn broader automation through measured accuracy and safe escalation.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/resolve.html).

---
title: "How to build LaunchPilot"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/launchpilot.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build LaunchPilot

Build a campaign cockpit for audiences, governed AI assets, approvals, channel activation, experiments, and optimization.

## In brief

- **Pattern:** AI marketing operations
- **First release:** One governed campaign
- **Build surface:** Developer Console

**LaunchPilot** follows the **AI marketing operations** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/launchpilot.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

LaunchPilot is now implemented and live-proven as a production Build This solution. Six managed record families cover campaigns, versioned consent-aware audiences, governed asset versions, approval-gated channel runs, experiments, and performance snapshots across five professional responsive workspaces. Current secured APIs and stored procedures provide create, view, edit, remove, favorite/unfavorite, relationships, evidence files, activity, Calendar, and the personal Favorites workspace. Universal Inbox and the reviewed Workflow approval contract own launch attention and decisions; channel runs retain frozen audience/asset inputs, budget, idempotency, and activation evidence, while provider activation remains prohibited until configured approval. The routed six-entity API journey and desktop/mobile Chromium experience passed against a disposable tenant. LaunchPilot is not yet a Template Library listing; exact-version packaging remains later work.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Move a campaign from a structured brief through approved content and audience selection to a measurable channel run, while preserving consent, claims, budget, and approval evidence.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Campaign** | Objective, owner, dates, budget, state, and target outcome. |
| **Audience** | Versioned segment definition, consent requirements, and estimated size. |
| **Asset** | Brief, content, brand/policy checks, version, and approval state. |
| **Channel run** | Provider, schedule, audience snapshot, delivery state, and external IDs. |
| **Experiment** | Variants, allocation, holdout, hypothesis, and decision rule. |
| **Performance snapshot** | Period, delivery, conversion, cost, and source evidence. |

**Relationship rule:** Freeze the audience, approved asset versions, budget, and experiment allocation used by each channel run so results remain explainable.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Campaign portfolio and launch calendar.
- Campaign workspace with brief, audience, assets, and approvals.
- Audience builder and consent summary.
- Asset review with claim/brand evidence.
- Experiment and performance dashboard.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Separate content authors, approvers, audience/data operators, and channel activators.
- Restrict customer fields and consent data at record/field scope.
- Require approval for unsupported claims, regulated content, budget changes, and channel activation.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Brief approved → audience and asset work created.
- Asset version → policy/brand checks → human approval.
- Audience snapshot + approved assets + budget → scheduled channel run.
- Provider webhook → normalized delivery/performance events.
- Experiment threshold → bounded recommendation, not silent budget movement.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Connect email, advertising, CRM, CMS, analytics, and consent systems.
- Use provider webhooks to reconcile accepted, delivered, failed, and conversion states.
- Keep provider credentials and raw audience exports out of pages and logs.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Ground generation in approved brand and product knowledge. Keep deterministic validation for required disclosures, consent, budgets, channel rules, and release state.

- Generate variants against a versioned brief and audience purpose.
- Attach the source brand/policy evidence used during review.
- Treat activation and budget changes as governed actions.
- Evaluate asset quality separately from campaign outcome.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Create one campaign and consented audience, generate two asset variants, approve one, send it through a sandbox channel, and ingest delivery results.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Prove unconsented contacts cannot enter the audience snapshot.
- Prove unapproved asset versions cannot launch.
- Deduplicate provider callbacks and reconcile failures.
- Freeze experiment inputs before comparing outcomes.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Make the first release excellent at campaign control and evidence. Add autonomous optimization only after measurement and authority ceilings are proven.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/launchpilot.html).

---
title: "How to build Northstar"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/northstar.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build Northstar

Build evidence-backed executive metrics, material-change signals, forecasts, scenarios, and replayable briefings.

## In brief

- **Pattern:** executive business intelligence
- **First release:** One replayable briefing
- **Build surface:** Developer Console

**Northstar** follows the **executive business intelligence** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/northstar.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

Northstar is now implemented and live-proven as a production Build This solution. Six managed dynamic/custom-field record families cover versioned metric definitions, source-watermarked observations, forecasts, material signals, scenarios, and frozen executive briefings across five professional responsive workspaces. Current secured APIs and stored procedures provide create, view, edit, remove, favorite/unfavorite, relationships, evidence files, activity, and the personal Favorites workspace. AI Insights are permission-aware derived synthesis only; briefings retain exact signal/evidence/assumption manifests, model and harness versions, reviewer/disposition, and frozen time, while financial commitments and operating writes remain approval-gated. Golden/disposable SQL verification, the routed six-entity journey, and desktop/mobile Chromium proof passed. Northstar is not yet a Template Library listing; exact-version packaging remains later work.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Compress operating changes into a small number of material signals and decisions, while letting leaders inspect the source, assumptions, owner, and confidence behind every claim.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Metric definition** | Formula, source, owner, cadence, unit, threshold, and active version. |
| **Metric observation** | Period, value, source watermark, quality state, and computed time. |
| **Target/forecast** | Versioned plan, assumptions, range, confidence, and owner. |
| **Signal** | Material change, severity, evidence, affected metric, and state. |
| **Scenario** | Baseline, changed drivers, outputs, confidence, and comparison. |
| **Briefing** | Frozen signals, narrative, decisions, attendees, and evidence manifest. |

**Relationship rule:** Every displayed number and narrative claim must resolve to versioned definitions, observations, source watermarks, and the briefing snapshot that used them.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Executive scorecard with freshness and quality indicators.
- Material-change queue.
- Metric drill-down with source and forecast history.
- Scenario comparison workspace.
- Briefing editor, snapshot, and decision log.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Separate broad aggregate visibility from sensitive underlying records.
- Restrict finance, people, customer, and departmental detail with existing permissions.
- Keep financial commitments and operating mutations behind action-specific approval.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Source update → validate freshness/quality → compute observation.
- Threshold/materiality rule → signal with owner and evidence.
- Scheduled synthesis → draft briefing.
- Briefing review → freeze evidence manifest and assumptions.
- Decision → assign follow-up work; never rewrite the historical briefing.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Ingest approved finance, CRM, support, product, and custom operational aggregates.
- Use bounded read APIs or scheduled imports with watermarks.
- Send approved follow-ups to the native work system while retaining a decision link.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Use AI to synthesize permitted evidence and explain changes, not to invent metrics or silently alter forecasts. Definitions, calculations, materiality rules, and source freshness remain explicit.

- Retrieve only evidence visible to the current reader.
- Require citations to metric observations and source records.
- Show uncertainty, stale inputs, and conflicting evidence.
- Freeze the exact evidence and prompt/harness version used in a briefing.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Ingest three KPIs, detect one threshold crossing, draft an evidence-linked weekly briefing, and freeze the reviewed briefing with one assigned decision.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Recompute known metric fixtures deterministically.
- Test stale, missing, and conflicting source data.
- Prove restricted readers cannot drill into protected evidence.
- Reconstruct a briefing from its frozen evidence manifest.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Executive trust comes from data lineage and restraint. Start with a handful of decision-driving metrics rather than a wall of charts.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/northstar.html).

---
title: "How to build TeamBox"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/teambox.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build TeamBox

Build a shared communications command center with channel normalization, AI triage, ownership, suggestions, and governed execution.

## In brief

- **Pattern:** universal team and AI inbox
- **First release:** One channel-to-completion loop
- **Build surface:** Developer Console

**TeamBox** follows the **universal team and AI inbox** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/teambox.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

TeamBox is now implemented and live-proven as a production Build This solution. Native Conversations retain thread and message lifecycle while Universal Inbox stays the bounded attention and ownership layer. Six managed dynamic/custom-field record families cover channel intake policy, queues, routing rules, reviewed classifications, SLA policy, and handoff playbooks across five professional responsive workspaces. Every managed record uses current secured create, view, edit, remove, favorite, relation, file, and activity contracts; native Conversations also provide create, update, internal reply, favorite, and safe removal. Classification evidence retains the conversation pointer, ActivityVersion, confidence, model/harness version, and reviewed disposition. Customer-facing replies and material actions remain stale-fenced and policy- or human-approval gated. The complete routed API journey, golden/disposable procedure policy, and desktop/mobile Chromium experience passed against a disposable tenant. TeamBox is not yet a Template Library listing; exact-version packaging remains later work.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Give a team one attention queue for incoming communications while preserving the native conversation, business record, ownership history, and approval boundary behind each item.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Conversation** | Native thread identity, participants, channel, status, and related business context. |
| **Message** | Inbound/outbound content, sender, time, channel metadata, and attachments. |
| **Inbox activity** | Attention item, activity version, priority, assignee, queue, and state. |
| **Classification** | Intent, urgency, sentiment, confidence, model/version, and evidence. |
| **Suggestion batch** | Prepared replies/actions tied to the current activity version. |
| **SLA/assignment event** | Ownership, handoff, timer, escalation, and completion history. |

**Relationship rule:** Universal Inbox points to conversations, forms, and business records; it does not replace them as the source of truth.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Shared inbox with queue, owner, priority, SLA, and channel filters.
- Conversation workspace with related customer/project context.
- Triage and reassignment panel.
- Suggested reply/action approval panel.
- Queue performance and handoff review.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Scope queues by role, DataRole, team, and location.
- Apply the related record's permission checks before showing context.
- Separate assignment, response, approval, and high-impact action capabilities.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Channel event → native conversation/message → inbox activity.
- Activity version → classify → route by deterministic rules plus permitted AI output.
- Assignee response or suggestion → approval policy → send/action.
- New message or source change → increment activity version and stale old preparation.
- SLA threshold → escalation and visible ownership event.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Connect email, SMS, forms, and authenticated inbound events.
- Normalize provider delivery callbacks into native message state.
- Use action-specific connectors for calendar, CRM, task, or external updates.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Use AI for triage, summaries, and prepared actions over permission-filtered context. Preserve the activity-version stale-context fence from preparation through execution.

- Classify intent/urgency with confidence and model version.
- Attach related-record evidence before suggesting work.
- Prepare structured replies and actions separately.
- Refuse or re-prepare when the activity version changes.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Receive one form or email, create the native conversation and inbox activity, classify and assign it, then let the assignee approve and send one prepared reply.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Test duplicate and out-of-order provider events.
- Prove queue and related-record permissions both apply.
- Prove stale suggestions cannot send or mutate.
- Trace channel receipt through assignment, approval, and delivery.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

The inbox should answer what needs attention now. Keep full domain history on the source conversation and related records.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/teambox.html).

---
title: "How to build RelateEverything"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/relateeverything.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build RelateEverything

Build a CRM where people, companies, work, communications, files, and custom records reveal their connected context.

## In brief

- **Pattern:** relationship-first CRM
- **First release:** One useful 360-degree view
- **Build surface:** Developer Console

**RelateEverything** follows the **relationship-first CRM** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/relateeverything.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

RelateEverything is now implemented and live-proven as a production Build This solution. Native Contacts provide complete create, view, edit, favorite, and safe removal while six managed dynamic/custom-field record families cover companies, workstreams, opportunities, relationship context, duplicate review, and connected automations across five professional responsive workspaces. Every managed record uses current secured create, view, edit, remove, favorite, relation, file, and activity contracts. Associations use canonical Records and the registered RecordRelations type, and graph expansion emits only nodes inside the current DataRole, location, tenant, SaaS, and direct-conversation participation envelope; edges require both authorized endpoints. Connected automations retain approval-required state instead of silently performing material mutations. The complete routed native-Contact and six-entity journey, golden/disposable procedure and graph policy check, and desktop/mobile Chromium experience passed against a disposable tenant. RelateEverything is not yet a Template Library listing; exact-version packaging remains later work.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Let a user open any important record and understand the surrounding people, companies, work, conversations, documents, and history without duplicating those records into a separate graph-shaped application.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Person** | Identity, contact details, consent, role, and relationship context. |
| **Company** | Organization identity, owner, segment, status, and commercial context. |
| **Relationship** | Typed source/target connection, direction, dates, status, and provenance. |
| **Work record** | Projects, tasks, events, opportunities, or custom operational records. |
| **Conversation/file** | Native communication or document linked into business context. |
| **Relationship event** | Created, changed, ended, inferred, or confirmed history. |

**Relationship rule:** Use typed relationships between canonical records. Do not copy a contact, file, or project merely to make it visible from another page.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Global search and recent context.
- Person and company 360-degree views.
- Relationship explorer with typed filters.
- Project/work page with people, files, tasks, and conversations.
- Relationship quality and duplicate-review queue.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Authorize both the relationship and each target record before displaying connected context.
- Protect sensitive fields even when the containing record is visible.
- Apply location and DataRole filters during graph traversal and AI retrieval.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Record created/imported → match candidates → confirm or create identity.
- Relationship change → append history and refresh relevant views.
- Connected trigger → create follow-up work on the correct source record.
- Merge review → authorized deterministic merge with preserved provenance.
- Important context change → inbox attention for affected owner.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Ingest contacts, calendars, files, messages, and CRM records with stable external IDs.
- Deduplicate through a reviewable matching process.
- Expose related context through authenticated APIs without returning inaccessible nodes.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Use relationship traversal to select relevant permitted context, then let AI summarize or suggest connections. AI-inferred relationships should remain distinguishable from confirmed facts.

- Filter accessible nodes before context assembly.
- Store provenance and confidence for inferred links.
- Require review before consequential inferred relationships drive mutations.
- Evaluate retrieval for both relevance and permission leakage.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Create people, companies, projects, tasks, files, and typed relationships, then build a company page that shows only the connected context the current user may see.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Traverse mixed permitted/restricted relationships without leaking names or counts.
- Test duplicate and directional relationship rules.
- Preserve provenance during merge and unlink operations.
- Verify connected-record automations target the canonical record.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Choose a small vocabulary of relationship types first. A consistent graph is more useful than hundreds of near-duplicate labels.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/relateeverything.html).

---
title: "How to build CustomerPortal"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/customerportal.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build CustomerPortal

Build a branded customer workspace that shares selected requests, files, messages, approvals, and milestones while protecting internal work.

## In brief

- **Pattern:** customer collaboration portal
- **First release:** One secure shared request
- **Build surface:** Developer Console

**CustomerPortal** follows the **customer collaboration portal** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/customerportal.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

CustomerPortal is now implemented and live-proven as a production Build This solution. Six managed record families use 54 database-backed dynamic/custom fields for customer requests, milestones, approvals, shared updates, private internal operations, and visibility reviews across five professional responsive pages. Explicit customer and internal-staff User Types have separate reviewed page menus and assignment policies; DataRoles plus shared/internal Locations enforce record visibility. External users completed create, view, edit, remove, 25-pixel favorite, registered relationship, Favorites, and customer-page workflows while direct detail, lists, search, graph nodes/edges, fields, and internal pages all concealed private records. The routed API/SQL isolation journey and desktop/mobile Chromium proof passed against a disposable tenant. CustomerPortal is not yet a Template Library listing; exact-version packaging remains later work.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Give customers a simple, branded place to collaborate on their own work while internal teams keep private fields, notes, assignments, AI guidance, and operating detail in the same governed application.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Customer** | Organization, account state, owner, branding, and commercial relationship. |
| **Portal member** | Verified identity, customer membership, status, and permitted role. |
| **Request** | Type, customer, submitter, status, owner, SLA, and shared summary. |
| **Comment/message** | Content, author, visibility, attachments, and related request. |
| **File** | Document metadata, owner, visibility, review state, and relationship. |
| **Approval/milestone** | Requested decision, due date, status, evidence, and shared update. |

**Relationship rule:** Derive customer membership server-side and explicitly mark shareable content; never trust a customer-supplied account or request identifier as authorization proof.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Branded customer home with their requests and milestones.
- New-request and document-upload forms.
- Shared request timeline with messages and files.
- Customer approval workspace.
- Internal sidecar with private notes, assignment, workflows, and AI guidance.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Create a customer user type using existing authorization—not a new authentication system.
- Require verified membership in the request's customer account.
- Enforce shared/private visibility server-side for fields, comments, files, and events.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Invitation → verified membership → portal access.
- Customer request → validation → internal queue and SLA.
- Internal status update → deliberately published customer update.
- File upload → scan/validation → shared or internal review state.
- Customer approval → immutable decision evidence → next internal action.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Use the same login/session APIs and custom domain/branding capabilities.
- Connect notifications and approved scheduling, billing, storage, or support systems.
- Keep storage/provider tokens and internal identifiers out of portal output.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Use AI for internal summarization, routing, and prepared responses over permitted context. Expose AI output to customers only through an explicitly designed and tested customer-visible experience.

- Separate internal-only and customer-visible context before retrieval.
- Prepare replies or status summaries as reviewable suggestions.
- Never allow private notes or inaccessible files into customer output.
- Record the approved content version that was published.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Invite one customer member, let them submit a request and file, route it internally, publish one status update, and capture one customer approval.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Test cross-customer identifier substitution on every route.
- Test private fields, comments, files, counts, and search results for leakage.
- Test revoked membership and expired invitation behavior.
- Trace every externally visible update to its author/approval.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Design from the customer's smallest useful journey first; the richer internal sidecar can grow without making the portal harder to use.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/customerportal.html).

---
title: "How to build CompanyIQ"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/companyiq.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build CompanyIQ

Build permission-aware document search and scheduled intelligence that connects knowledge to customers, risks, and opportunities.

## In brief

- **Pattern:** company knowledge and opportunity intelligence
- **First release:** Search plus one evidence-backed insight
- **Build surface:** Developer Console

**CompanyIQ** follows the **company knowledge and opportunity intelligence** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/companyiq.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

CompanyIQ is now implemented and live-proven as a production Build This solution. Five managed record families use 40 database-backed dynamic/custom fields for knowledge sources, business context, evidence-backed insights, cited evidence, and governed suggested actions across five professional responsive pages. Current secured typed APIs and reviewed stored procedures provide create, view, edit, safe remove, gray/gold 25-pixel favorites, registered relationships, files, activity, ingestion, and cited semantic search. Retrieval applies the represented user's tenant, DataRole, location, record, field, and CanAiReadRecords envelope before context assembly and preserves text plus visual evidence through the canonical 256, 1024, and 1998-dimensional multimodal lanes. Golden/disposable database policy, the routed lifecycle/favorite/relation/AI journey, and desktop/mobile Chromium proof passed. CompanyIQ is not yet a Template Library listing; exact-version packaging remains later work.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Make company knowledge searchable with source evidence, then combine permitted documents and business records to surface a small number of reviewable risks or opportunities.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **AI source** | Canonical document/source identity, origin, ownership, permission metadata, and processing state. |
| **Document element/chunk** | Extracted text and visual structure with source position and metadata. |
| **Business record** | Customer, contact, sale, project, support, meeting, or custom source context. |
| **Insight** | Typed opportunity/risk, summary, confidence, owner, state, and expiry. |
| **Insight evidence** | Exact source chunks and business records supporting or contradicting the insight. |
| **Suggested action** | Reviewable task, opportunity, follow-up, or external action. |

**Relationship rule:** Reuse the canonical AI source → element → chunk → visual index → embedding pipeline and relate evidence back to canonical business records; do not create a parallel knowledge-table family.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Natural-language knowledge search with citations.
- Source/document detail with processing state.
- Customer 360 with related knowledge and history.
- Scheduled insight queue.
- Evidence review and approved-action workspace.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Apply source, record, field, DataRole, and location access before retrieval.
- Preserve document ownership and effective access when chunking and embedding.
- Require normal action permissions even when AI discovered the opportunity.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Source accepted → extract text and visual evidence → chunk → embed → index.
- Source or permission change → bounded reprocessing and access refresh.
- Scheduled account scan → insight with evidence and expiry.
- Human review → approve, dismiss, or correct insight.
- Approved action → native opportunity/task/workflow with source link.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Accept approved files and source connectors through bounded ingestion.
- Use the current multimodal embedding profile for text, image, and mixed evidence.
- Send approved opportunities into the native CRM/work system, not directly into database tables.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Use secured multimodal retrieval so tables, diagrams, screenshots, and text can all remain evidence. Current vector lanes are 256, 1024, and 1998 dimensions; any manual MRL truncation must be L2-normalized consistently for storage and query.

- Preserve source location and visual evidence during extraction.
- Filter authorized candidates before assembling model context.
- Return evidence links and distinguish contradiction or uncertainty.
- Evaluate retrieval and insight quality against fixed permission-aware fixtures.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Ingest a small approved document set, answer one cited question, relate evidence to one customer, and run one reviewable opportunity scan that can create a task.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Test text, table, diagram, and screenshot retrieval.
- Prove revoked source access disappears from search and AI context.
- Verify embedding dimensions, normalization, and query/storage parity.
- Trace each insight to source/version and business evidence.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Prove trustworthy search before proactive intelligence. Insight quality cannot exceed retrieval quality and permission correctness.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/companyiq.html).

---
title: "How to build OpsAtlas"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/opsatlas.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build OpsAtlas

Build an owned, revisioned operating-memory product with permission-aware answers, evidence, review work, knowledge gaps, and governed actions.

## In brief

- **Pattern:** AI operational knowledge core
- **First release:** One maintained collection and cited answer
- **Build surface:** Developer Console

**OpsAtlas** follows the **AI operational knowledge core** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/opsatlas.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

OpsAtlas is now implemented and live-proven as a production Build This solution. Five managed record families use 35 database-backed dynamic/custom fields for operating domains, approved source registers, review programs, gap triage, and governed workflow links across five professional responsive pages. The native Knowledge Core provides owned draft creation, immutable revisions, explicit publish/archive/restore, collections, owner assignment, due reviews, questions, feedback, gap analytics, favorites, relations, files, and activity through current typed APIs and reviewed stored procedures. Published AI-eligible knowledge enters the canonical multimodal source pipeline; cited answers apply tenant, DataRole, location, field, record, and CanAiReadRecords scope before context and preserve visual evidence across the 256, 1024, and 1998-dimensional lanes. The routed author-to-publish/favorite/relation/ingest/answer journey, database policy, and desktop/mobile Chromium proof passed. OpsAtlas is not yet a Template Library listing; exact-version packaging remains later work.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Turn a small set of approved operating procedures into maintained Knowledge Core records that employees and agents can search in context, verify against exact revisions, and use to start the right governed workflow.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Knowledge item** | Canonical title, body, type, authority, lifecycle, AI/support eligibility, and RecordId. |
| **Immutable revision** | Versioned content, change note, author, publication state, and content hash. |
| **Collection** | Reader journey, audience, default owner, review policy, and parent collection. |
| **Owner/review cycle** | Accountable user or DataRole, due date, Task, outcome, and next review. |
| **Question/feedback** | Missing answer, repeated occurrence, assignment, response, rating, and source context. |
| **Citation/evidence** | Exact item, revision, freshness, source/page/visual identity, and permitted related records. |

**Relationship rule:** Relate each procedure to the products, departments, locations, assets, cases, work orders, conversations, files, and workflows it governs; a relation improves context but never grants access.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Knowledge home with collections, search, freshness, and health.
- Item editor/view with ownership, revisions, publication, relations, and citations.
- Review queue connected to Tasks and Universal Inbox.
- Question, feedback, and knowledge-gap workspace.
- Employee/agent answer surface with source and freshness evidence.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Separate read, edit, publish, manage ownership/reviews, link, ask/answer, and support-learning capabilities.
- Apply tenant, DataRole, location, record, field, and `CanAiReadRecords` checks before retrieval or model context.
- Keep customer-safe and internal-only collections distinct and recheck disclosure at response time.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Draft → review/edit → permission-checked publish → immutable revision citation.
- Review due → Task/Inbox attention → confirm current, revise/republish, reassign, or archive.
- No authoritative answer → Knowledge Question → assignment/answer → optional GeneratedCandidate Draft.
- Usage/negative feedback/repeated gaps → secured health signal and owner follow-up.
- Resolved support case → structured sanitization → owner/review Task → Draft candidate; authorized publication only.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Ingest only approved current sources with explicit audience, owner, authority, review policy, and AI eligibility.
- Preserve files, PDF pages, images, tables, diagrams, and screenshots through the canonical multimodal AI pipeline.
- Expose read-only diagnostics separately from knowledge; route any material action through existing workflow/GoClaw approval contracts.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Use Knowledge Core as the governed source layer for secured semantic and multimodal retrieval. Only Published, AI-eligible revisions enter normal RAG, and every answer retains exact source/revision/freshness evidence.

- Index approved revisions through the existing source, element, chunk, visual-index, and embedding chain.
- Filter by the represented user's full security envelope before context assembly.
- Prefer current Official/Verified evidence and surface conflicts, staleness, or missing authority.
- Create a question or escalation instead of fabricating an unsupported answer.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Create one customer-safe collection with an owner and 30-day review policy, publish three approved procedures, relate one to a business record, answer one question with an exact citation, and turn one missing answer into a reviewable Knowledge Question.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Prove Draft, archived, stale-policy, internal-only, other-tenant, other-location, and AI-denied material cannot enter a normal answer.
- Prove citations resolve to the exact immutable revision and source evidence.
- Prove duplicate review cycles/questions/support candidates remain idempotent.
- Change source activity or permissions and verify stale context or revoked access fails closed.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Start with one operating area whose owner will actually review it. A small current corpus with accountable citations is more useful than a large unowned document dump.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/opsatlas.html).

---
title: "How to build Headless SaaS DB"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/headless-saas-db.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build Headless SaaS DB

Build a managed, permission-aware SaaS backend for custom web, mobile, desktop, or existing frontends.

## In brief

- **Pattern:** API-first SaaS backend
- **First release:** One authenticated end-to-end resource
- **Build surface:** Developer Console

**Headless SaaS DB** follows the **API-first SaaS backend** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/headless-saas-db.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

Headless SaaS DB is now implemented and live-proven as a production Build This solution. Five managed record families use 35 database-backed dynamic/custom fields for domain objects, API client profiles, inbound contracts, webhook policies, and correlation evidence across five professional responsive pages. The exported server-side TypeScript client covers schema/search and complete record, favorite, relation, inbound-endpoint, webhook, delivery-retry, and correlation-log operations. A working React administration client keeps the live app credential and physical routing inside its same-origin BFF while showing accurate 25-pixel gray/gold favorite stars. The routed public-API journey proved create, read, update, remove cleanup, favorite/unfavorite, relation add/remove, read-only denial, webhook create/rotate, safe correlation evidence, and absence of SQL/provider authority; current golden and disposable procedure policy plus desktop/mobile Chromium proof passed. It is not yet a Template Library listing; exact-version packaging remains later work.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Let a custom frontend use BuildWithHQ records, relationships, workflows, files, AI, and integrations without exposing SQL, provider secrets, tenant infrastructure, or authorization decisions to the client.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Domain record** | The customer, project, transaction, content, or custom object your product owns. |
| **Relationship** | Reviewed connections between domain records. |
| **API client/profile** | App-bound client metadata and external credential-source reference. |
| **Inbound endpoint** | Declared event contract, authentication, validation, and processing policy. |
| **Webhook subscription** | Allowed event, target, signing state, delivery policy, and status. |
| **Operation evidence** | Correlation ID, actor/client, bounded outcome, and safe failure detail. |

**Relationship rule:** Treat client-supplied identifiers as query targets only; derive the builder account, SaaS app, tenant account, user, role, and location from verified server identity.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Your custom customer-facing frontend.
- Internal admin/operations views for the same records.
- Developer Console API-client and integration setup.
- Webhook delivery and correlation-log diagnostics.
- Optional BuildWithHQ pages for back-office workflows.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Use app-bound credentials or user sessions appropriate to the caller.
- Enforce tenant, record, field, DataRole, and location scope in the backend.
- Give every client only the operations and fields its use case requires.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Authenticated request → identity/context derivation → validation → typed service.
- Typed service → reviewed stored procedure → bounded response.
- State change → workflow/event → signed webhook delivery.
- Inbound event → authenticate → validate → deduplicate → queue/process.
- Failure → safe problem response and correlation evidence.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Start from the generated OpenAPI contract and current REST routes.
- Use externally referenced credentials; never persist raw bearer values in profiles or frontend code.
- Put specialized libraries/services in an appliance with declared endpoints and egress.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Call secured AI capabilities through the API or declared tools. The browser sends the user's request; the server performs authorization, retrieval, context assembly, and governed action handling.

- Keep model/provider credentials server-side.
- Apply the same data permissions used by normal record APIs.
- Return bounded evidence and correlation identifiers.
- Represent material AI mutations as authorized action contracts.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** From a small custom frontend, authenticate, list and create one permitted record type, invoke one workflow, receive one signed webhook, and trace the whole exchange by correlation ID.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Generate/validate clients against the current OpenAPI document.
- Test cross-app, cross-tenant, field, role, and location denials.
- Test duplicate requests/events and webhook retries.
- Confirm no secrets, SQL details, or internal routes appear in output/logs.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Build one complete API resource before designing a broad generic backend. Its auth, errors, idempotency, events, and observability become the pattern for the rest.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/headless-saas-db.html).

---
title: "How to build CaseFlow"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/caseflow.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build CaseFlow

Build controlled case stages, intake, work queues, documents, decisions, approvals, SLAs, and replayable history.

## In brief

- **Pattern:** case and process management
- **First release:** One intake-to-decision path
- **Build surface:** Developer Console

**CaseFlow** follows the **case and process management** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/caseflow.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

CaseFlow is now implemented and live-proven as a production Build This solution. Seven managed record families use 53 database-backed dynamic/custom fields for cases, parties, stage history, tasks, evidence, decisions, and approvals across five professional responsive workspaces. Current secured typed APIs and reviewed stored procedures provide complete lifecycle, gray/gold 25-pixel favorites, registered relationships, files, and activity. The server-owned CaseFlow transition boundary fixes creation at Intake, serializes adjacent stages, rejects direct, stale, invalid, and out-of-order changes, and requires an approved Checklists & Signoffs run before Decision or Closed. Five role policies and two locations preserve permission scope. The routed intake-to-decision API journey and desktop/mobile Chromium proof passed. CaseFlow is not yet a Template Library listing; exact-version packaging remains later work.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Move a case through a defined process while accumulating participants, documents, messages, work, decisions, and approvals—with every transition explainable and properly authorized.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Case** | Type, subject, customer, owner, stage, priority, SLA, and current version. |
| **Participant** | Person/organization role, effective dates, and contact relationship. |
| **Stage transition** | From/to stage, actor, time, reason, expected version, and evidence. |
| **Task/checklist** | Required work, owner, due date, completion, and stage dependency. |
| **Document/communication** | Native file or conversation related to the case with visibility. |
| **Decision/approval** | Question, recommendation, authority, outcome, reason, and evidence. |

**Relationship rule:** Make the case the coordination record while participants, files, conversations, and business records remain canonical and permissioned in their native models.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Role-aware case queue with SLA and stage filters.
- Structured intake form.
- Case 360 with timeline, parties, files, messages, and tasks.
- Reviewer checklist and evidence workspace.
- Decision/approval and audit replay views.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Scope case visibility by type, role, customer, geography/location, and sensitivity.
- Protect sensitive fields/documents independently from case access.
- Define who may transition, decide, approve, reopen, and export.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Intake → validate required identity/data → triage.
- Stage transition → expected-state and required-check validation.
- Missing document → request and timer; receipt → review task.
- SLA threshold → escalation and ownership event.
- Recommendation → authorized decision/approval → immutable transition evidence.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Accept forms, messages, documents, and authenticated API submissions.
- Use managed notifications and signature/identity connectors where required.
- Export only bounded authorized case data through reviewed APIs.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Use AI to summarize long histories, identify missing information, and prepare next actions. It must cite permitted case evidence and cannot make regulated or material decisions unless an explicit policy and authorized action allow it.

- Assemble context from the case and accessible related records.
- Distinguish facts, missing data, and recommendations.
- Bind suggestions to the case/activity version so changed evidence makes them stale.
- Capture reviewer corrections as evaluation evidence.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Submit one case type, route it to triage, request and receive one document, complete a review checklist, and record one authorized decision.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Test invalid and out-of-order stage transitions.
- Test SLA clocks, pause rules, and escalation fixtures.
- Prove sensitive evidence is absent for restricted reviewers.
- Replay the case timeline into the same explainable final state.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Model the happy path and three important exceptions first. Case systems become unmanageable when every exception is encoded as a new status.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/caseflow.html).

---
title: "How to build AssetOps"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/assetops.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build AssetOps

Build customer, location, asset, inspection, work-order, technician, parts, and service-history operations.

## In brief

- **Pattern:** asset and field operations
- **First release:** One inspection-to-work-order loop
- **Build surface:** Developer Console

**AssetOps** follows the **asset and field operations** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/assetops.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

AssetOps is now implemented and live-proven as a production Build This solution. Five product-specific record families use 47 database-backed dynamic/custom fields for sites, assets, inspection findings, parts usage, and service history across five professional responsive workspaces. Native Contacts own customers and technicians; native Work Orders own maintenance state and assignments; native Checklists & Signoffs own versioned inspections and proof; native Files own photos and documents. Current secured typed APIs and reviewed stored procedures provide complete lifecycle, 25-pixel gray/gold favorites, relationships, activity, valid work-order transitions, optimistic concurrency, exact proof-location matching, and server-enforced location and assignee scope. The routed customer-to-asset-to-inspection-to-completed-work journey and desktop/mobile Chromium proof passed. AssetOps is not yet a Template Library listing; exact-version packaging remains later work.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Connect each physical asset to its customer/site hierarchy, current condition, inspections, service work, technicians, parts, documents, photos, and complete maintenance history.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Customer/location** | Customer, property, facility, room, route, and location hierarchy. |
| **Asset** | Type, serial, parent asset, site, warranty, state, and service attributes. |
| **Inspection** | Template/version, inspector, readings, answers, photos, result, and time. |
| **Issue** | Finding, severity, source inspection, status, and required response. |
| **Work order** | Asset, issue, priority, assignee, schedule, state, labor, and resolution. |
| **Part/service evidence** | Parts, measurements, manuals, images, invoices, notes, and historical events. |

**Relationship rule:** Use parent/child and typed relationships for customer → site → asset/component, then attach inspections, issues, work, people, files, and invoices to their canonical records.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Operations dashboard and work queue.
- Customer/site/asset 360-degree detail.
- Mobile-friendly inspection and issue capture.
- Dispatcher schedule and technician assignment.
- Work-order execution with parts, photos, signature, and closeout.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Scope technicians and managers by assigned work, team, customer, and location.
- Protect customer, warranty, invoice, and sensitive site fields separately.
- Define who may inspect, dispatch, close, reopen, or approve chargeable work.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Scheduled/due asset → inspection task.
- Failed reading/check → issue → work-order rule.
- Work order → assignment, schedule, SLA, and customer notification.
- Technician closeout → required evidence validation → asset history.
- Recurring condition → maintenance suggestion for human review.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Use mobile forms/files for readings, signatures, photos, and offline-tolerant field capture where supported.
- Connect approved inventory, accounting, calendar, mapping, or messaging providers.
- Ingest device/telemetry events through authenticated, deduplicated endpoints or an appliance service.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Use permitted service history, readings, manuals, images, and inspection evidence to summarize condition and prepare maintenance work. Do not let a prediction silently change asset state or schedule chargeable service.

- Preserve visual inspection evidence and source metadata.
- Relate the model's evidence to the exact asset and service event.
- Express recommendations with confidence and maintenance horizon.
- Require approval for work creation/scheduling according to policy.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Create one customer, site, and asset; complete a mobile inspection; turn one failed check into a work order; assign and close it with photo evidence.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Test location and assignment restrictions in list, search, and detail views.
- Test duplicate telemetry and inspection submissions.
- Require closeout evidence and valid state transitions.
- Trace each maintenance suggestion to readings and history.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Start with one asset class and one inspection template. Generalize only after the field workflow works end to end.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/assetops.html).

---
title: "How to build ActiveWorkplace"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/activeworkplace.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build ActiveWorkplace

Build a Wave-like shared coordination surface around any permitted Record and its secured recursive relationship graph.

## In brief

- **Pattern:** recursive work coordination
- **First release:** Pin one Record and coordinate its graph
- **Build surface:** Developer Console

**ActiveWorkplace** follows the **recursive work coordination** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/activeworkplace.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

ActiveWorkplace is now implemented and live-proven as a production Build This solution. Two managed record families use 16 database-backed dynamic/custom fields for pinnable work items and reusable graph playbooks across four professional responsive workspaces. The native first-class ActiveWorkplace module owns idempotent pinning, bounded cyclic graphs, participants and responsibilities, deterministic Pulse, retained activity and snapshots, and read-only playback; Universal Inbox remains the attention layer. Current secured typed APIs and reviewed stored procedures provide complete record lifecycle, 25-pixel gray/gold favorites, registered relationships, stale-write protection, and current tenant, DataRole, location, and AI-read enforcement. The routed pin-to-playback journey, golden/disposable procedure policy, cleanup, and desktop/mobile Chromium proof passed. ActiveWorkplace is not yet a Template Library listing; exact-version packaging remains later work.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Let a team pin an existing business Record, see the permitted connected work around it, assign explicit responsibilities, notice inactivity, and replay retained history without copying the underlying business data or creating a second permission system.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Root Record** | The existing permitted customer, case, project, asset, opportunity, conversation, or other canonical Record. |
| **ActiveWorkplace** | Coordination name, owner, Pulse, bounded graph policy, stale timing, and current version. |
| **Participant assignment** | A User, GoClaw, or Workflow plus responsibility, watch/action settings, and approval policy. |
| **Workplace event** | Immutable comments, participant changes, Pulse transitions, graph changes, and correlation evidence. |
| **Graph snapshot** | A bounded identity-and-topology snapshot used for playback; it does not copy business payloads. |
| **Inbox attention** | The de-duplicated At Risk or Stale item that points back to the root and workplace. |

**Relationship rule:** Keep every business item in its native module. Reuse typed Record Relations for the Active Graph and store only bounded identities/topology in workplace snapshots.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- My/All ActiveWorkplaces list with search and Pulse filters.
- Pin-record picker over currently visible Records.
- Workplace detail with root, Pulse, graph, participants, and activity.
- Participant/responsibility editor for eligible Users, GoClaws, and Workflows.
- Read-only Graph Playback with a clear historical banner and Return to current action.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Require current read/edit permission to pin and manage the root.
- Reauthorize every graph node by tenant, SaaS app, DataRole, and location before display.
- Require independent AI-read access for a GoClaw backing user; assignment never grants it.
- Intersect playback identities with current authorization and remove all historical mutation paths.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Visible Record -> pin once -> initial graph snapshot and owner participant.
- Meaningful update or related Record change -> refresh activity/Pulse and retained state.
- Waiting expiry or inactivity -> Active/At Risk/Stale transition -> create or touch Inbox attention.
- Eligible participant assignment -> responsibility recorded without changing its authority.
- Resolved -> retain history and prevent accidental active duplicate behavior according to policy.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Use Universal Inbox for human attention rather than creating a separate alert queue.
- Use existing GoClaw events/suggestions/actions for AI participation and material approval.
- Use normal workflow definitions and APIs for deterministic business actions.
- Keep ActiveWorkplace tenant-local; involve AI Orchestration only when an AI job actually runs.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

AI is optional. A GoClaw can monitor, research, summarize, and prepare work only through its represented user's current AI-read envelope. Record Pulse itself is deterministic and does not need a model.

- Start with a non-acting GoClaw watcher and a clear responsibility.
- Retrieve only currently authorized graph records and fields.
- Represent any material next step as the existing governed suggestion/action contract.
- Keep human approval for customer-facing or material work until policy and harness evidence support more authority.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Pin one case or opportunity, show a cyclic three-record graph, add one person and one read-only GoClaw, let inactivity create one Inbox item, and replay the workplace with every write control removed.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Prove a hidden-location graph branch and its edges are omitted.
- Prove a GoClaw without independent CanAiReadRecords cannot be assigned.
- Evaluate Pulse twice and prove the second run does not duplicate Inbox attention.
- Change current location access and prove playback cannot restore the old view.
- Retry pinning and prove the same active root workplace is returned.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

The feature is strongest when the graph is meaningful and bounded. Begin with one work type, a small relation vocabulary, and a Pulse rule the team already understands.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/activeworkplace.html).

---
title: "How to build FieldService"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/fieldservice.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build FieldService

Build customer, service-area, scheduling, job, estimate, approval, evidence, and follow-up operations for field teams.

## In brief

- **Pattern:** field-service management
- **First release:** One request-to-closeout service call
- **Build surface:** Developer Console

**FieldService** follows the **field-service management** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/fieldservice.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

FieldService is now implemented and live-proven as a production Build This solution refreshed from the existing reference implementation. Template-owned Change Requests use 12 database-backed dynamic/custom fields while native Contacts own customers and team profiles, native Work Orders own jobs and legal transitions, native Calendar owns scheduling, native Files and Checklists & Signoffs own evidence and approval, and native Conversations and Universal Inbox own communications and attention. Six professional responsive workspaces support dispatcher, customer, technician, schedule, evidence, manager approval, and follow-up work. Current secured typed APIs and reviewed stored procedures provide complete lifecycle, 25-pixel gray/gold favorites, registered relationships, optimistic concurrency, server-enforced location and assignee scope, and read-only governed AI/estimator boundaries. The routed request-to-approved-closeout journey, golden/disposable procedure policy, template bundle checks, and desktop/mobile Chromium proof passed. Tenant billing remains explicitly deferred and this is not yet a Template Library listing.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Move one customer request through triage, scheduling, assignment, field execution, evidence, authorization, closeout, and follow-up while keeping dispatchers, technicians, managers, and customers inside their own experience and data scope.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Customer/service location** | Contact, address, service area, location scope, equipment, and history. |
| **Service request** | Intake channel, issue, priority, customer, site, and triage state. |
| **Work order** | Job scope, schedule, assigned user, status, version, labor, and completion. |
| **Estimate/approval** | Line items, amount, authority, decision, reason, and evidence. |
| **Calendar/resource** | Appointment, duration, technician/resource assignment, and conflicts. |
| **Service evidence** | Notes, readings, images, files, signature, communications, and follow-up. |

**Relationship rule:** Keep Contacts, Calendar, Work Orders, files, conversations, payments, and Inbox attention canonical in their first-class modules, linked to the service request and customer graph.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Dispatcher queue and service-area calendar.
- Customer, site, and equipment history.
- Technician work-order workspace with mobile evidence capture.
- Estimate and manager/customer approval page.
- Closeout evidence and follow-up workspace.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Create User Types for dispatcher, technician, manager, and customer experiences.
- Scope work by DataRole, assigned technician/team, customer, and Location.
- Protect pricing, customer, and site fields independently.
- Require explicit authority for assignment, estimate approval, closeout, and reopen.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Inbound request -> triage -> service-area and priority routing.
- Approved scope -> schedule and assign technician/resource.
- Field arrival -> checklist, readings, notes, photos, and status transitions.
- Estimate -> authorized approval with retained evidence.
- Closeout -> customer notice, evidence, and scheduled follow-up.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Receive email, SMS, forms, and authenticated API requests through the Universal Inbox.
- Use Calendar, mapping, inventory, accounting, and messaging connectors as needed.
- Put specialized estimating or device logic behind a declared appliance endpoint.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Use permitted service history, manuals, text, images, and readings to answer field questions and prepare summaries or estimates. Keep chargeable, customer-facing, and state-changing work inside explicit approval and action contracts.

- Retrieve only the technician's permitted customer, asset, and job evidence.
- Cite the exact source record, file, page, image, or reading.
- Bind suggestions to the current work-order/activity version.
- Require configured approval before creating an estimate, message, charge, or material state transition.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Accept one service request, schedule and assign it, complete a field checklist with photo evidence, approve an estimate, close the work order, and schedule customer follow-up.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Test cross-location, unassigned-technician, customer, and field-level denials.
- Test schedule conflicts and stale work-order versions.
- Prove duplicate requests and follow-up retries are idempotent.
- Trace request, work, approval, evidence, and follow-up by correlation ID.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Start with one trade, one service-call type, and one closeout checklist. Generalize only after dispatch-to-follow-up works end to end.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/fieldservice.html).

---
title: "How to build Reservations"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/reservations.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build Reservations

Build bookable products, capacity, assignments, calendars, tenant-controlled payments, and pre/post-service follow-up.

## In brief

- **Pattern:** reservations and booking operations
- **First release:** One book-to-follow-up path
- **Build surface:** Developer Console

**Reservations** follows the **reservations and booking operations** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/reservations.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

Reservations is now implemented and live-proven as a production Build This solution over the current first-class Reservations module. One managed Reservation Policies record family uses 10 database-backed dynamic/custom fields, while native Reservation Products, Reservations, Contacts, Calendar, Files, Favorites, Record Graph, Record Activity, tenant payment controls, and durable pre/post-service follow-ups retain their current secured typed APIs and reviewed stored procedures. Five professional responsive workspaces cover booking, operations, product/capacity setup, customers, and payment/follow-up. The routed journey proved product setup/update/deactivation, authenticated booking, idempotent replay, server-locked capacity, party limits, assignment, Contact and Calendar creation, free-booking payment state, paid-booking payment-method enforcement, stale-write rejection, follow-up update, favorite, relation, file evidence, check-in/completion, audited cancellation, and cleanup. Golden/disposable procedure policy and desktop/mobile Chromium proof passed. Anonymous checkout and Template Library packaging remain intentionally separate.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Let an authenticated customer or operator select a bookable product, protect capacity, create or reuse the Contact, place the service on the Calendar, assign an eligible tenant user or resource, coordinate tenant-controlled payment, and deliver scheduled follow-up.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Bookable product** | Duration, buffers, price/currency, capacity, party limits, defaults, and follow-up timing. |
| **Reservation** | Contact, product, start/end, party size, status, assignment, location, version, and notes. |
| **Capacity/resource** | Availability, hold, location, eligible resource/user, and conflict state. |
| **Calendar event** | Reservation-linked schedule entry and assigned participants/resources. |
| **Payment intent** | Tenant payment policy, provider reference, amount, currency, and synchronized state. |
| **Follow-up work** | Before/after-service time, template, channel, delivery state, attempts, and evidence. |

**Relationship rule:** Keep Contacts, Calendar, payment orchestration, communications, tenant users, Locations, and resources canonical, with the Reservation as the lifecycle record that links them.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Bookable-product setup.
- Availability and authenticated booking flow.
- Reservation list and detail workspace.
- Calendar, assignment, and capacity view.
- Payment state and pre/post-service follow-up queue.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Separate operator, assigned provider, manager, and customer User Type experiences.
- Scope reservations by DataRole, Location, assignment, and Contact relationship.
- Protect payment references, internal notes, and customer fields independently.
- Require explicit permissions for product setup, assignment, cancellation, payment actions, and override.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Select product/time -> validate availability -> protect capacity -> create reservation.
- Create or reuse Contact -> assign eligible user/resource -> create Calendar event.
- Free booking -> confirm; paid booking -> tenant-controlled charge intent and synchronized state.
- Before-service due time -> queue and send configured reminder/follow-up.
- Completion/cancellation -> release capacity and schedule or cancel after-service communication.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Use tenant-owned payment configuration and provider orchestration; keep credentials and provider calls server-side.
- Use Calendar and communications workers for durable schedules and delivery evidence.
- Use authenticated inbound endpoints and signed webhooks for external channel/provider state.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

Use AI only where it improves permitted scheduling, customer-service, or follow-up work. It may summarize context or draft a message, but it cannot invent availability, confirm a charge, or bypass reservation state rules.

- Retrieve only permitted Contact, Reservation, product, and communication context.
- Treat capacity and payment state as deterministic service results, not model output.
- Bind drafts and suggestions to the current reservation/activity version.
- Require policy or human approval for customer-facing or material actions.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Configure one paid service, book it for an existing or new Contact, protect one capacity slot, assign one tenant user, create its Calendar event and charge intent, then deliver one before- and one after-service follow-up.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Test cross-tenant, DataRole, Location, assignment, and Contact denials.
- Test concurrent capacity claims, buffers, party limits, and stale reservation versions.
- Prove booking, charge-intent, provider-state, and follow-up retries are idempotent.
- Trace reservation, calendar, payment reference, and communication evidence by correlation ID.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Make availability and capacity deterministic before polishing the booking screen. A beautiful form cannot repair an overbooked schedule.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/reservations.html).

---
title: "How to build Support Tickets"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/support-tickets.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build Support Tickets

Turn selected inbound email addresses into durable support-ticket queues inside Universal Inbox.

## In brief

- **Pattern:** technical support ticketing
- **First release:** One mailbox-to-resolution support path
- **Build surface:** Developer Console

**Support Tickets** follows the **technical support ticketing** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/support-tickets.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

Support Tickets is now implemented and live-proven as a production Build This solution over native Conversations and Universal Inbox. One managed Support Playbooks record family uses 14 database-backed dynamic/custom fields across five professional responsive workspaces for command, ticket conversation, customer context, mailbox/service-level configuration, and knowledge-backed resolution. Current secured typed APIs and reviewed stored procedures provide mailbox-owner ticketing configuration, atomic stable ticket allocation, assignment, priority, customer reply, explicit resolution, automatic reopen on later inbound mail, and Inbox ActivityVersion stale-context protection. Support playbooks provide complete create, view, edit, safe remove, 25-pixel gray/gold favorite, registered relationship, file, and activity lifecycle. The routed mailbox-to-resolution journey, golden/disposable procedure policy, cleanup, and desktop/mobile Chromium proof passed. This is not yet a Template Library listing.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Let an account owner enable ticketing on a selected email address, give each new conversation a stable human-readable ticket number, and move the request through assignment and explicit resolution states without creating a second message or permission system.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Email channel** | The existing inbound ChannelConnection plus the Ticketing switch, short prefix, and next-number allocator. |
| **Conversation** | The canonical email thread and message history; replies remain on the same source conversation. |
| **Inbox ticket** | The attention record, stable mailbox-scoped key, assignee, priority, SLA, resolution state, and ActivityVersion. |
| **Customer context** | The permitted Contact, company, subscription, product, or service records related to the conversation. |
| **Resolution evidence** | Notes, files, approvals, sent messages, status changes, and correlation/audit history. |
| **Knowledge evidence** | Permission-aware articles, manuals, policies, and prior records used to prepare an answer. |

**Relationship rule:** Keep Conversations and Messages canonical. Universal Inbox contributes ticket identity, attention, routing, ownership, SLA, and resolution state, while related customer and product records remain in their native modules.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Support-ticket queue with owner, priority, SLA, channel, and resolution filters.
- Ticket conversation workspace with message history and related customer context.
- Account-owner email settings with a per-address Ticketing checkbox and prefix.
- Knowledge/evidence viewer for grounded support research.
- Resolution, reopen, escalation, and service-level reporting views.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Allow only an active tenant account owner to configure mailbox ticketing.
- Derive tenant, SaaS application, user, DataRole, and Location scope from verified server identity.
- Authorize the source Conversation and related records on every read; a ticket number grants no access.
- Require action-specific permission and configured approval for customer-facing or material operations.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Ticket-enabled inbound email -> canonical Conversation -> atomically allocated ticket key -> Inbox attention.
- Reply on the same thread -> retain ticket key -> increment ActivityVersion -> invalidate stale preparation.
- Assignment or response -> New/Open/Waiting Customer/Waiting Internal/Snoozed state.
- Resolved or Closed ticket receives a new reply -> reopen and return to attention.
- SLA threshold or exception -> escalate through the same Inbox ownership and audit path.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Use the existing inbound-email connector and delivery worker; do not expose provider credentials to the browser.
- Use Contacts, subscriptions, products, files, and custom records as related context rather than copying them into ticket tables.
- Use Knowledge Core and secured vector retrieval for evidence-backed suggestions.
- Use GoClaw suggestion and action contracts when AI prepares or executes governed work.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

AI may classify, summarize, research permitted evidence, and draft a reply. It must apply CanAiReadRecords, tenant, DataRole, and Location security before context assembly, preserve the ActivityVersion stale-context fence, and never send or mutate material state outside the configured approval policy.

- Load the current ticket and only currently permitted related records.
- Retrieve source-cited knowledge through the secured AI/vector path.
- Bind every draft or proposed action to the current Inbox ActivityVersion.
- Route customer-facing or material actions through the canonical suggestion, approval, and execution contracts.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Enable Ticketing for one support email address, receive a new thread, allocate one stable key, assign and reply to it, resolve it, then prove a later reply reopens the same ticket without changing its number.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Prove a non-owner cannot read or change mailbox ticketing configuration.
- Send concurrent first messages and prove ticket numbers are unique and monotonically allocated per mailbox.
- Retry ingestion and prove the same Conversation keeps one ticket key.
- Resolve a ticket, receive a reply, and prove it reopens with a higher ActivityVersion.
- Disable Ticketing and prove existing tickets retain identity while new conversations remain ordinary Inbox items.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Enable ticketing only on addresses that represent a support promise. Keep general mailboxes conversational so the team's Inbox stays useful instead of turning every email into a case.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/support-tickets.html).

---
title: "How to build Checkoff & Approval"
section: "How-To Do This"
canonical_url: "https://support.buildwithhq.com/how-to-do-this/checkoff-approval.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How to build Checkoff & Approval

Build reusable checklists whose items can require notes, documents, photos, and governed approval before work is accepted.

## In brief

- **Pattern:** checklists, evidence, and signoff
- **First release:** One evidence-backed checklist
- **Build surface:** Developer Console

**Checkoff & Approval** follows the **checklists, evidence, and signoff** pattern. This guide turns the [product concept](https://buildwithhq.com/buildthis/checkoff-approval.html)  into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Note

Checkoff & Approval is now implemented and live-proven as a production Build This solution over native Checklists & Signoffs, Files, Workflow, Universal Inbox, Favorites, Record Graph, and Record Activity. One managed Verification Programs record family uses 12 database-backed dynamic/custom fields across five professional responsive workspaces for command, template editing, attached work, evidence review, and signoff/revision. Current secured typed APIs and reviewed stored procedures provide template list/read/create/revision-fenced update/deactivation, exact run snapshots, bounded item revisions, verified document/photo evidence, idempotent submission, Inbox ActivityVersion fencing, reject/revise/resubmit, and human approval. The public Developer API recipe now includes the full template lifecycle. The routed evidence-to-approval journey, golden/disposable procedure and developer-grant policy, cleanup, OpenAPI/SDK checks, and desktop/mobile Chromium proof passed. This is not yet a Template Library listing.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [First-app guide](../getting-started/your-first-app.html) [Page editor](../builder-guide/page-editor.html) [Workflows](../builder-guide/workflows.html)

## Define the outcome before the screens

Attach a bounded checklist to a record, ticket, project, or work order; let authorized users complete its items with required proof; and submit the finished run through the existing Workflow approval system without creating a parallel approval engine.

Note

Treat every name in this blueprint as a starting point. Use the language of the industry you are serving, but preserve clear ownership, status, permission, and audit boundaries.

## 1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

| Record type | What it holds |
| --- | --- |
| **Checklist template** | Reusable name, version, item order, proof requirements, and activation state. |
| **Checklist item template** | Instruction, required state, proof policy, order, and optional responsible role. |
| **Checklist run** | The versioned checklist attached to one authorized source record, current status, owner, and revision. |
| **Run item** | Completion state, actor, completion time, note, and optimistic-concurrency revision. |
| **Evidence** | A native File relationship identifying the document or photo supplied as proof for one item. |
| **Signoff** | The existing Workflow run, approval step, Inbox attention, decision, comment, and audit evidence. |

**Relationship rule:** Keep Files, Workflow approvals, Inbox attention, users, DataRoles, Locations, and the attached business record canonical. The checklist stores only its template/run lifecycle and explicit links to that evidence and approval work.

## 2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

- Checklist-template editor with ordered items and proof rules.
- Attached checklist list on records, tickets, projects, and work orders.
- Run workspace with up to 1,000 bounded items, progress, notes, documents, and photos.
- Submit-for-signoff and reviewer decision panel.
- Rejection, revision, proof replacement, resubmission, and approval history.

Use [Puck](../builder-guide/page-editor.html)  for the normal visual experience. Keep stable block identity when using [Monaco advanced JSON mode](../builder-guide/raw-json-mode.html)  so future template upgrades can merge safely.

## 3. Set access before adding automation

- Authorize the attached source record before listing or opening its checklists.
- Apply tenant, DataRole, Location, record, and action permissions to every run, item, and evidence operation.
- Require current file access for proof downloads; an evidence link never grants access to a File.
- Use the existing Workflow decision permissions and Inbox ActivityVersion fence for signoff.

User Type menus organize page links for each audience. An entitled published page may also be requested directly when it is absent from the menu. Menus do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

## 4. Add the core workflows

- Create or attach run -> snapshot exact template version and ordered items.
- Complete item -> validate required note/file/photo proof -> record actor, revision, and evidence links.
- All required items complete -> submit once -> create or reuse one Workflow approval and Inbox item.
- Reject -> return to editable state -> replace proof or edit items -> resubmit with current revision.
- Approve -> lock the accepted result while preserving the complete activity, file, and Workflow evidence chain.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

## 5. Connect channels and outside systems

- Use native Files and attachment upload APIs for documents and photos.
- Use Workflow for approval decisions and Universal Inbox for reviewer attention.
- Use Record Relations to attach runs to any authorized business record without copying that record.
- Use background workers for scanning, thumbnails, delivery, or other asynchronous evidence processing.

Use [managed connections](../builder-guide/external-api-connections.html), [OAuth connectors](../api/connectors-and-oauth.html), [inbound endpoints](../api/inbound-endpoints.html), and [webhooks](../api/webhooks.html). Put specialized SDKs or private processing behind a declared [appliance endpoint](../builder-guide/appliances-and-endpoints.html); never expose provider credentials to a page.

## 6. Add AI as a governed layer

AI may summarize a permitted checklist or highlight missing evidence, but it cannot mark work complete, manufacture proof, approve signoff, or read attached records/files beyond the represented user's normal and AI-specific permissions.

- Assemble context only from the authorized run, source record, and readable evidence.
- Keep completion and proof validation deterministic.
- Bind suggestions to the current run revision and Inbox ActivityVersion.
- Route any material follow-up through the normal suggestion, permission, and approval contracts.

AI and retrieval must apply `CanAiReadRecords`, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

## 7. Ship one complete vertical slice

**Recommended first release:** Attach one checklist to a work order, complete its required items with a note and photo, submit it for Workflow signoff, reject it once, replace the proof, resubmit, and approve it while preserving one coherent audit chain.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

## 8. Validate, package, and operate

- Test another tenant, DataRole, Location, source-record denial, and unauthorized file download.
- Test two users completing the same item and stale run revisions.
- Test duplicate submit/approve/reject requests for idempotency.
- Test reject, edit, proof replacement, resubmit, approve, and activity history.
- Test empty, typical, and 1,000-item runs without returning unbounded unrelated records.

Publish a reviewed exact version as a [template](../builder-guide/templates-forking.html)  when the pattern is reusable. If you sell it, complete the [marketplace preparation](../selling/preparing-a-template.html)  checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

**Built-in data path:** React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.

Tip

Make proof requirements explicit per item. A photo or document should demonstrate a specific completed step, not become an unstructured dumping ground attached to the whole job.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/how-to-do-this/checkoff-approval.html).

---

# Section: First Class Modules

---
title: "Connected work"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/connected-work.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Connected work

Find records you can read, explore their visible connections, and open their native pages to work on them.

## In brief

- **Runtime key:** module.connected-work
- **Experience:** Read-only record discovery
- **Security:** Server-enforced

Use Connected work when a task crosses several modules and you need to follow the records that connect it. This is a read-only discovery view; create, edit, remove, and relationship management stay on the native record pages.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.connected-work. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Find records you can read, explore their visible connections, and open their native pages to work on them.

## Key capabilities

- Search by saved record title with Search records, then use Load more records for additional results.
- Choose a result to see its visible related work. Explore follows a connected record without copying it.
- Open native record and Open record use persisted page associations. When several destinations are available, choose the page you want; no destination is guessed.
- A display-limit notice means the shown connections are bounded, not the complete relationship count. Explore a connected record to continue.
- If loading fails, Try again repeats the requested search or connection lookup under your current access.

## Common uses

- Follow a meeting to its related work order or file.
- Find the native page for a record discovered through another module.
- Review visible relationships before opening the owning record.

## How it connects

Connected work reads the existing secured record search and Record Graph. It links to the original records and their persisted native pages; it does not create a second record store or a new mutation route.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Every search and connection read uses the verified user, tenant organization, and SaaS app. Personal ownership, DataRole, location, private-record, and action rules remain enforced by the secured services. A visible relationship or page link never grants access to its target.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Add the validated `module.connected-work` block to an active, entitled published page.
2. Reuse that page in the UserType menus that need it; each menu may use its own label for the same page.
3. Verify native page associations for the records your users need. Test no destination, one destination, and several destinations without inventing a page key.
4. Test empty results, loading, retry, additional search results, bounded connections, and denied records as representative users.

## Build a professional Connected work dashboard

These six registry-backed presentation blocks let a designer turn the secured Connected work API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/record-graph`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/connected-work-sample.json`, its executable authenticated page at `pages/first-class/connected-work-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Connected work projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Visible relations, connected records, types, and recent links |
| `entity-list` | `core.entity-list` | Highly connected records inside the current scope |
| `progress-list` | `core.progress-list` | Distribution by relation type or owning module |
| `series-chart` | `core.series-chart` | Relationship creation and removal |
| `data-grid` | `core.presentation-grid` | One bounded edge page with both endpoints authorized |
| `timeline` | `core.timeline` | Create, update, remove, source loss, and graph traversal events |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "connected-work-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Connected work",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "relations",
            "label": "Visible relations",
            "value": 3218,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "records",
            "label": "Connected records",
            "value": 1407,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "types",
            "label": "Relation types",
            "value": 18,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "new",
            "label": "Added this week",
            "value": 96,
            "format": "number",
            "tone": "warning"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "connected-work-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Highly connected records",
        "hasMore": true,
        "items": [
          {
            "id": "connected-work-sample-1",
            "recordId": "connected-work-record-1",
            "primary": "Acme Field Services",
            "secondary": "Contact - 34 visible relations",
            "status": {
              "key": "connected",
              "label": "Connected",
              "tone": "success"
            },
            "trailing": "34 links"
          },
          {
            "id": "connected-work-sample-2",
            "recordId": "connected-work-record-2",
            "primary": "Acme Field Services - Follow-up",
            "secondary": "Contact - 34 visible relations - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "connected-work-sample-3",
            "recordId": "connected-work-record-3",
            "primary": "Acme Field Services - West region",
            "secondary": "Contact - 34 visible relations - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "connected-work-sample-4",
            "recordId": "connected-work-record-4",
            "primary": "Acme Field Services - Customer response",
            "secondary": "Contact - 34 visible relations - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "connected-work-sample-5",
            "recordId": "connected-work-record-5",
            "primary": "Acme Field Services - Regional operations review with a deliberately long title",
            "secondary": "Contact - 34 visible relations - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "connected-work-sample-6",
            "recordId": "connected-work-record-6",
            "primary": "Acme Field Services - Completed preview",
            "secondary": "Contact - 34 visible relations - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "connected-work-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Relations by type",
        "items": [
          {
            "key": "customer",
            "label": "Customer of",
            "value": 1210,
            "maximum": 3218,
            "displayValue": "1210",
            "tone": "primary",
            "status": {
              "key": "customer",
              "label": "Customer of",
              "tone": "primary"
            }
          },
          {
            "key": "attached",
            "label": "Attached to",
            "value": 1084,
            "maximum": 3218,
            "displayValue": "1084",
            "tone": "success",
            "status": {
              "key": "attached",
              "label": "Attached to",
              "tone": "success"
            }
          },
          {
            "key": "depends",
            "label": "Depends on",
            "value": 924,
            "maximum": 3218,
            "displayValue": "924",
            "tone": "warning",
            "status": {
              "key": "depends",
              "label": "Depends on",
              "tone": "warning"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "connected-work-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Relationship activity",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Created",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Removed",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "connected-work-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Visible relationships",
        "columns": [
          {
            "key": "from",
            "label": "From",
            "type": "text",
            "align": "left"
          },
          {
            "key": "relation",
            "label": "Relationship",
            "type": "text",
            "align": "left"
          },
          {
            "key": "to",
            "label": "To",
            "type": "text",
            "align": "left"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "created",
            "label": "Created",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "connected-work-row-1",
            "recordId": "connected-work-record-1",
            "cells": {
              "from": "Acme Field Services",
              "relation": "Customer of",
              "to": "WO-1048",
              "status": {
                "key": "active",
                "label": "Active",
                "tone": "success"
              },
              "created": "2026-09-04T11:11:00Z"
            }
          },
          {
            "id": "connected-work-row-2",
            "recordId": "connected-work-record-2",
            "cells": {
              "from": "Acme Field Services - Follow-up",
              "relation": "Customer of",
              "to": "WO-1048",
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "created": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "connected-work-row-3",
            "recordId": "connected-work-record-3",
            "cells": {
              "from": "Acme Field Services - West region",
              "relation": "Customer of",
              "to": "WO-1048",
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "created": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "connected-work-row-4",
            "recordId": "connected-work-record-4",
            "cells": {
              "from": "Acme Field Services - Customer response",
              "relation": "Customer of",
              "to": "WO-1048",
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "created": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "connected-work-row-5",
            "recordId": "connected-work-record-5",
            "cells": {
              "from": "Acme Field Services - Regional operations review with a deliberately long title",
              "relation": "Customer of - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "to": "WO-1048",
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "created": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "connected-work-row-6",
            "recordId": "connected-work-record-6",
            "cells": {
              "from": "Acme Field Services - Completed preview",
              "relation": "Customer of",
              "to": "WO-1048",
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "created": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 3218,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "connected-work-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Relationship activity",
        "hasMore": true,
        "items": [
          {
            "id": "connected-work-event-1",
            "recordId": "connected-work-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Relationship created",
            "description": "Acme Field Services was related to WO-1048.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "connected-work-event-2",
            "recordId": "connected-work-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Relationship created - Follow-up",
            "description": "Acme Field Services was related to WO-1048. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "connected-work-event-3",
            "recordId": "connected-work-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Relationship created - West region",
            "description": "Acme Field Services was related to WO-1048. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "connected-work-event-4",
            "recordId": "connected-work-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Relationship created - Customer response",
            "description": "Acme Field Services was related to WO-1048. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "connected-work-event-5",
            "recordId": "connected-work-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Relationship created - Regional operations review with a deliberately long title",
            "description": "Acme Field Services was related to WO-1048. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "connected-work-event-6",
            "recordId": "connected-work-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Relationship created - Completed preview",
            "description": "Acme Field Services was related to WO-1048. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface ConnectedWorkPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface ConnectedWorkPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: ConnectedWorkPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function ConnectedWorkPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: ConnectedWorkPresentationProps) {
  if (error) return <p role="alert">The Connected work presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Connected work presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Connected work</p>
        <h1>Connected work</h1>
        <p>Fictional connected-record design data; the live page searches visible records and opens their native owners.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/record-graph`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "connected-work-live",
      "_type": "module.connected-work",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Use the native module for lifecycle actions. A short connection list is not an all-records report, and menu placement never substitutes for data permissions.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/connected-work.html).

---
title: "Knowledge finder"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/knowledge-finder.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Knowledge finder

Search accessible Knowledge Core articles, filter publication state, preview current text, and open the native article page.

## In brief

- **Runtime key:** module.knowledge-finder
- **Experience:** Read-only article discovery
- **Security:** Server-enforced

Use Knowledge finder for everyday article lookup. This read-only view does not create, edit, publish, archive, or remove articles; Open article takes you to the native Knowledge Core page for those separately authorized actions.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.knowledge-finder. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Search accessible Knowledge Core articles, filter publication state, preview current text, and open the native article page.

## Key capabilities

- Enter a search and choose All accessible articles, Published, Draft, or Archived in Publication state, then select Search articles.
- Use Previous article page and Next article page to browse the applied search and publication-state filter.
- Preview an article to read its current publication state, authority level, revision, summary, and article text.
- Draft and archived previews explicitly say they are unavailable as published citations. Selecting a filter never grants access to those articles.
- Open article resolves the record's persisted native page choices. If no destination is available, use the displayed unavailable-state guidance rather than guessing a route.
- Try again retries the failed search page or article preview using current permissions.

## Common uses

- Find an operating procedure by its title or search text.
- Review an accessible draft before opening Knowledge Core.
- Check an article's current revision and publication state.

## How it connects

Knowledge finder uses the existing secured Knowledge Core list and detail services. It displays the current article text and opens the same canonical record in its owning page; it does not generate AI answers or queue indexing.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

The verified user, tenant organization, SaaS app, and persisted page identity determine the current request. Knowledge Core applies its record, Personal ownership, DataRole, location, private-record, and action-specific permissions. Search terms, publication filters, menu labels, and client-supplied IDs are query targets, never authorization proof.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Add the validated `module.knowledge-finder` block to an active, entitled published page.
2. Reuse the page across UserType menus with the labels each audience needs.
3. Ensure the intended native Knowledge Core pages are associated with their records, then test the Open article choices.
4. Test empty, loading, retry, page navigation, preview, and denied access with representative users, including the distinction between readable drafts and published citations.

## Build a professional Knowledge finder dashboard

These six registry-backed presentation blocks let a designer turn the secured Knowledge finder API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/knowledge-articles`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/knowledge-finder-sample.json`, its executable authenticated page at `pages/first-class/knowledge-finder-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Knowledge finder projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Published, draft, due-review, stale, and gap counts |
| `entity-list` | `core.entity-list` | Important articles, owners, freshness, and use |
| `progress-list` | `core.progress-list` | Distribution by freshness, lifecycle, category, or owner |
| `series-chart` | `core.series-chart` | Draft, publish, review, use, and gap activity |
| `data-grid` | `core.presentation-grid` | One bounded article page with lifecycle evidence |
| `timeline` | `core.timeline` | Revision, publication, review, retrieval, feedback, gap, and archive |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "knowledge-finder-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Knowledge finder",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "published",
            "label": "Published",
            "value": 684,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "review",
            "label": "Review due",
            "value": 31,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "draft",
            "label": "Drafts",
            "value": 24,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "gaps",
            "label": "Open gaps",
            "value": 12,
            "format": "number",
            "tone": "danger"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "knowledge-finder-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Knowledge needing attention",
        "hasMore": true,
        "items": [
          {
            "id": "knowledge-finder-sample-1",
            "recordId": "knowledge-finder-record-1",
            "primary": "Escalation playbook",
            "secondary": "Support operations - owner: Maya Chen",
            "status": {
              "key": "review-due",
              "label": "Review due",
              "tone": "warning"
            },
            "trailing": "14 uses"
          },
          {
            "id": "knowledge-finder-sample-2",
            "recordId": "knowledge-finder-record-2",
            "primary": "Escalation playbook - Follow-up",
            "secondary": "Support operations - owner: Maya Chen - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "knowledge-finder-sample-3",
            "recordId": "knowledge-finder-record-3",
            "primary": "Escalation playbook - West region",
            "secondary": "Support operations - owner: Maya Chen - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "knowledge-finder-sample-4",
            "recordId": "knowledge-finder-record-4",
            "primary": "Escalation playbook - Customer response",
            "secondary": "Support operations - owner: Maya Chen - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "knowledge-finder-sample-5",
            "recordId": "knowledge-finder-record-5",
            "primary": "Escalation playbook - Regional operations review with a deliberately long title",
            "secondary": "Support operations - owner: Maya Chen - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "knowledge-finder-sample-6",
            "recordId": "knowledge-finder-record-6",
            "primary": "Escalation playbook - Completed preview",
            "secondary": "Support operations - owner: Maya Chen - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "knowledge-finder-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Knowledge freshness",
        "items": [
          {
            "key": "current",
            "label": "Current",
            "value": 611,
            "maximum": 684,
            "displayValue": "611",
            "tone": "success",
            "status": {
              "key": "current",
              "label": "Current",
              "tone": "success"
            }
          },
          {
            "key": "due",
            "label": "Due soon",
            "value": 42,
            "maximum": 684,
            "displayValue": "42",
            "tone": "warning",
            "status": {
              "key": "due",
              "label": "Due soon",
              "tone": "warning"
            }
          },
          {
            "key": "stale",
            "label": "Stale",
            "value": 31,
            "maximum": 684,
            "displayValue": "31",
            "tone": "danger",
            "status": {
              "key": "stale",
              "label": "Stale",
              "tone": "danger"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "knowledge-finder-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Knowledge lifecycle",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Published",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Reviewed",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "knowledge-finder-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Authorized knowledge",
        "columns": [
          {
            "key": "article",
            "label": "Article",
            "type": "text",
            "align": "left"
          },
          {
            "key": "owner",
            "label": "Owner",
            "type": "text",
            "align": "left"
          },
          {
            "key": "freshness",
            "label": "Freshness",
            "type": "status",
            "align": "left"
          },
          {
            "key": "uses",
            "label": "Uses",
            "type": "number",
            "align": "right"
          },
          {
            "key": "review",
            "label": "Next review",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "knowledge-finder-row-1",
            "recordId": "knowledge-finder-record-1",
            "cells": {
              "article": "Escalation playbook",
              "owner": "Maya Chen",
              "freshness": {
                "key": "due",
                "label": "Review due",
                "tone": "warning"
              },
              "uses": 14,
              "review": "2026-09-10T00:00:00Z"
            }
          },
          {
            "id": "knowledge-finder-row-2",
            "recordId": "knowledge-finder-record-2",
            "cells": {
              "article": "Escalation playbook - Follow-up",
              "owner": "Maya Chen",
              "freshness": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "uses": 15,
              "review": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "knowledge-finder-row-3",
            "recordId": "knowledge-finder-record-3",
            "cells": {
              "article": "Escalation playbook - West region",
              "owner": "Maya Chen",
              "freshness": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "uses": 16,
              "review": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "knowledge-finder-row-4",
            "recordId": "knowledge-finder-record-4",
            "cells": {
              "article": "Escalation playbook - Customer response",
              "owner": "Maya Chen",
              "freshness": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "uses": 17,
              "review": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "knowledge-finder-row-5",
            "recordId": "knowledge-finder-record-5",
            "cells": {
              "article": "Escalation playbook - Regional operations review with a deliberately long title",
              "owner": "Maya Chen - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "freshness": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "uses": 18,
              "review": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "knowledge-finder-row-6",
            "recordId": "knowledge-finder-record-6",
            "cells": {
              "article": "Escalation playbook - Completed preview",
              "owner": "Maya Chen",
              "freshness": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "uses": 19,
              "review": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 684,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "knowledge-finder-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Knowledge activity",
        "hasMore": true,
        "items": [
          {
            "id": "knowledge-finder-event-1",
            "recordId": "knowledge-finder-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Review requested",
            "description": "Escalation playbook entered its scheduled review window.",
            "actor": "Knowledge Core",
            "tone": "warning"
          },
          {
            "id": "knowledge-finder-event-2",
            "recordId": "knowledge-finder-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Review requested - Follow-up",
            "description": "Escalation playbook entered its scheduled review window. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "knowledge-finder-event-3",
            "recordId": "knowledge-finder-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Review requested - West region",
            "description": "Escalation playbook entered its scheduled review window. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "knowledge-finder-event-4",
            "recordId": "knowledge-finder-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Review requested - Customer response",
            "description": "Escalation playbook entered its scheduled review window. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "knowledge-finder-event-5",
            "recordId": "knowledge-finder-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Review requested - Regional operations review with a deliberately long title",
            "description": "Escalation playbook entered its scheduled review window. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "knowledge-finder-event-6",
            "recordId": "knowledge-finder-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Review requested - Completed preview",
            "description": "Escalation playbook entered its scheduled review window. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface KnowledgeFinderPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface KnowledgeFinderPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: KnowledgeFinderPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function KnowledgeFinderPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: KnowledgeFinderPresentationProps) {
  if (error) return <p role="alert">The Knowledge finder presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Knowledge finder presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Knowledge finder</p>
        <h1>Knowledge finder</h1>
        <p>Fictional article-discovery design data; the live page searches accessible articles and opens their native owner.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/knowledge-articles`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "knowledge-finder-live",
      "_type": "module.knowledge-finder",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Keep article lifecycle work in Knowledge Core. This search page is not an AI answer, and an accessible draft is not automatically eligible for a published citation.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/knowledge-finder.html).

---
title: "Universal Inbox"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/universal-inbox.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Universal Inbox

Collects configured external email, optional support tickets, SMS, web-form submissions, and other inbound communications into one secured attention layer where unsorted work stays visible and routing rules can classify, prioritize, assign, and queue it for action.

## In brief

- **Runtime key:** core.universal-inbox
- **Experience:** Inbound work & triage
- **Security:** Server-enforced

Use Universal Inbox as the front door for communication and work arriving from outside the organization. It gives users one place to see both unclassified incoming items and communication already sorted into a queue, owner, priority, or workflow.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is core.universal-inbox. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Collects configured external email, optional support tickets, SMS, web-form submissions, and other inbound communications into one secured attention layer where unsorted work stays visible and routing rules can classify, prioritize, assign, and queue it for action.

## Key capabilities

- Receive configured inbound email and SMS through native Conversations and messages.
- Let an account owner enable Ticketing per inbound email address and assign stable mailbox-scoped ticket numbers.
- Use New, Open, WaitingCustomer, WaitingInternal, Snoozed, Resolved, and Closed as one controlled ticket-resolution lifecycle.
- Receive web-form submissions and other authenticated inbound source events without losing their native source record.
- Keep unmatched or unsorted items visible for human triage instead of dropping them into a hidden channel silo.
- Apply deterministic routing rules and permitted AI classification to assign queues, owners, tags, priorities, and due/SLA attention.
- Open the full native source context, prepare replies or actions, approve governed suggestions, snooze, reassign, and complete work.
- Increment `ActivityVersion` when new source activity arrives so stale drafts or actions cannot execute.

## Optional support tickets per email address

Ticketing is an email-channel setting, not a second inbox. An account owner opens Email ticketing setup, checks **Ticketing** for the intended inbound address, and chooses a 2–12 character letter/number prefix. New conversations on that address receive a permanent key such as `SUP-000123`. Other mailboxes remain ordinary Inbox channels.

The ticket reuses the Inbox queue, assignment, priority, SLA, activity, approval, and status controls. Resolving or closing it changes the Inbox attention state; it does not rewrite the native Conversation. A later inbound reply retains the ticket key, reopens attention, and makes preparation against the older `ActivityVersion` stale.

## Common uses

- One intake queue for support, sales, service, operations, and customer requests.
- A technical-support mailbox with durable ticket identity and resolution state.
- Sorting unknown inbound communication before it reaches a team or person.
- Shared ownership, SLA, escalation, and GoClaw-assisted preparation across external channels.

## How it connects

Email and SMS normalize into native Conversations; web forms remain native submissions; other inbound endpoints keep their canonical source records. Inbox items point to those sources as the attention layer. Sorting changes queue/ownership/attention state—it does not move or copy the underlying conversation, form, or business record.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

An item is visible only when the current user can access its source record and effective queue scope. Routing never grants source access. GoClaw preparation, approval, and execution reapply the user's record/DataRole/location envelope, AI-read gate, action permission, and current ActivityVersion.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- For the standard experience, the tenant shell already renders `UniversalInboxBell` in the top bar and opens the complete `UniversalInbox` panel. No custom React is required. Builders may also place the registered `core.universal-inbox` block on a published page and launch it from a User Type menu.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. For a standard BuildWithHQ app, write no React. Confirm the authorized user can see the built-in Inbox bell in the tenant top bar; it opens the native Inbox panel.
2. If users also need a permanent workspace, create a shared page with PageKey `Inbox`, add the registered `core.universal-inbox` block, save, validate, and publish it.
3. For every intended User Type, choose **Add existing** on the Inbox page, order it in that menu, and choose **Save menu**. The resulting link opens `/?page=Inbox`; menu placement adds navigation without granting page or Inbox data authority.
4. Connect each supported external channel through its reviewed email, SMS, web-form, or inbound-endpoint contract.
5. For a support mailbox, open Email ticketing setup as the tenant account owner, check Ticketing, and select a unique operational prefix.
6. Define the default Unsorted/Triage queue so unmatched communication remains visible and owned operationally.
7. Add routing rules for source, recipient/line, form, intent, customer, location, priority, or other permitted context.
8. Configure queues, assignment, SLA/escalation, and the existing permissions for the people who will triage or act.
9. Enable GoClaw preparation only for permitted users/queues, then test the top-bar panel and menu page plus new tickets, same-thread replies, reopen after resolution, ordinary mailboxes, duplicate delivery, late events, and stale-activity cases end to end.
10. Use the optional React examples below only when maintaining a custom tenant runtime, replacing the application shell, or building a headless same-origin presentation.

## React is optional

The standard tenant application already mounts the Inbox bell and native panel in its shell. Channel setup, ticketing, routing, queues, permissions, and GoClaw policy are configuration work; they do not require a React component. Use one of the following integrations only when you want the Inbox somewhere other than the standard top-bar panel.

| Experience | What to add |
| --- | --- |
| Normal BuildWithHQ app | Nothing. Use the built-in top-bar Inbox. |
| Menu-launched Inbox page | Add the registered `core.universal-inbox` block to a published page and add that PageKey to each intended User Type menu. |
| Custom tenant shell | Mount `UniversalInboxBell` and open `UniversalInbox` in your dialog. |
| Headless presentation | Inject the official authenticated client into your own markup. |

### Menu-launched embedded Inbox page

Create a shared page named **Inbox**. In Puck, select **Universal Inbox** from BuildWithHQ components. Or switch to Monaco advanced JSON and paste this complete page document. Save the draft, validate it, and publish it.

```
[
  {
    "_id": "universal-inbox-page",
    "_type": "core.universal-inbox",
    "props": {},
    "children": []
  }
]
```

Back in the selected User Type, choose **Add existing** on the Inbox page and then **Save menu**. The saved menu item has this shape. Use the Design studio rather than writing `SaasAppMenus` directly because the authoring API applies version and route checks.

```
{
  "id": "inbox",
  "label": "Inbox",
  "targetType": "Page",
  "pageKey": "Inbox",
  "sortOrder": 0
}
```

The menu opens `/?page=Inbox`. The runtime bootstrap verifies that this User Type may open that PageKey, returns the authorized component contract, and then the block loads only Inbox rows visible to the signed-in user. The top-bar bell remains available; both presentations share the same tenant-session client and server authorization.

### Custom tenant-runtime page component

The registered page renderer is already bundled in BuildWithHQ. If you maintain a custom tenant-runtime fork, this self-contained equivalent mounts the complete native queue, ticketing settings, detail, activity, workflow approval, and human-state controls. The native component imports its own styles.

```
import {
  UniversalInbox,
  createUniversalInboxHttpClient,
} from "@buildwithhq/universal-inbox";
import { getTenantAccessToken, tenantSessionFetch } from "./api";
import { ensureCsrfToken } from "./webSecurity";

const inboxClient = createUniversalInboxHttpClient({
  accessToken: getTenantAccessToken,
  csrfToken: ensureCsrfToken,
  fetchImplementation: tenantSessionFetch,
});

interface DedicatedInboxPageProps {
  readonly initialInboxItemId?: string;
}

export function DedicatedInboxPage({
  initialInboxItemId,
}: DedicatedInboxPageProps) {
  return (
    <main aria-label="Inbox workspace" style={{ minWidth: 0, width: "100%" }}>
      <UniversalInbox
        key={initialInboxItemId ?? "all"}
        client={inboxClient}
        initialInboxItemId={initialInboxItemId}
      />
    </main>
  );
}
```

### Custom tenant-shell top bar and dialog

Use this only when replacing the standard shell. Do not mount a second bell alongside the one that is already present.

```
import { useEffect, useState } from "react";
import {
  UniversalInbox,
  UniversalInboxBell,
  createUniversalInboxHttpClient,
} from "@buildwithhq/universal-inbox";
import { getTenantAccessToken, tenantSessionFetch } from "./api";
import { ensureCsrfToken } from "./webSecurity";

const inboxClient = createUniversalInboxHttpClient({
  accessToken: getTenantAccessToken,
  csrfToken: ensureCsrfToken,
  fetchImplementation: tenantSessionFetch,
});

export function InboxTopBarControl() {
  const [open, setOpen] = useState(false);
  const [initialInboxItemId, setInitialInboxItemId] = useState<string>();

  useEffect(() => {
    if (!open) return undefined;
    const closeOnEscape = (event: KeyboardEvent) => {
      if (event.key === "Escape") setOpen(false);
    };
    window.addEventListener("keydown", closeOnEscape);
    return () => window.removeEventListener("keydown", closeOnEscape);
  }, [open]);

  return (
    <>
      <UniversalInboxBell
        client={inboxClient}
        onOpenInbox={(inboxItemId) => {
          setInitialInboxItemId(inboxItemId);
          setOpen(true);
        }}
      />

      {open && (
        <div
          className="bwhq-inbox-shell-overlay"
          onMouseDown={(event) => {
            if (event.target === event.currentTarget) setOpen(false);
          }}
        >
          <section
            aria-label="Universal Inbox"
            aria-modal="true"
            className="bwhq-inbox-shell-dialog"
            role="dialog"
          >
            <header>
              <div><small>Attention workspace</small><h2>Universal Inbox</h2></div>
              <button type="button" onClick={() => setOpen(false)}>Close</button>
            </header>
            <UniversalInbox
              key={initialInboxItemId ?? "all"}
              client={inboxClient}
              initialInboxItemId={initialInboxItemId}
            />
          </section>
        </div>
      )}
    </>
  );
}
```

#### Minimal custom-shell layout CSS

```
.bwhq-inbox-shell-overlay {
  position: fixed;
  z-index: 1000;
  inset: 0;
  display: grid;
  place-items: center;
  padding: 24px;
  background: rgb(15 23 42 / 55%);
}

.bwhq-inbox-shell-dialog {
  display: grid;
  grid-template-rows: auto minmax(0, 1fr);
  width: min(1440px, 100%);
  height: min(900px, calc(100vh - 48px));
  overflow: hidden;
  border-radius: 18px;
  background: white;
  box-shadow: 0 30px 90px rgb(15 23 42 / 30%);
}

.bwhq-inbox-shell-dialog > header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 16px;
  padding: 16px 20px;
  border-bottom: 1px solid #e2e8f0;
}

.bwhq-inbox-shell-dialog h2 { margin: 2px 0 0; }
.bwhq-inbox-shell-dialog .bwhq-inbox { min-height: 0; }

@media (max-width: 760px) {
  .bwhq-inbox-shell-overlay { padding: 0; }
  .bwhq-inbox-shell-dialog { width: 100%; height: 100vh; border-radius: 0; }
}
```

### Unstyled headless list, detail, and resolution

This version owns only presentation. Authentication remains an injected application concern and every list, detail, and mutation is still reauthorized by the server. The client deliberately accepts same-origin API paths only; reverse-proxy `/api/inbox` through the headless application's origin instead of putting SQL credentials, database names, or cross-origin service secrets in the browser.

```
import { useEffect, useMemo, useState } from "react";
import {
  createUniversalInboxHttpClient,
  type InboxItemDetail,
  type InboxQueueItem,
  type UniversalInboxClient,
} from "@buildwithhq/universal-inbox";

interface HeadlessInboxAuth {
  readonly accessToken: () => string | null | undefined;
  readonly csrfToken: () => string | null | undefined;
  readonly authenticatedFetch?: typeof fetch;
}

interface UnstyledInboxProps {
  readonly client: UniversalInboxClient;
}

const itemTitle = (item: InboxQueueItem) =>
  item.subject?.trim() || item.source.sourceKey || item.source.sourceType;

export function UnstyledHeadlessInbox({ client }: UnstyledInboxProps) {
  const [ticketingOnly, setTicketingOnly] = useState(false);
  const [assignedToMe, setAssignedToMe] = useState(false);
  const [items, setItems] = useState<readonly InboxQueueItem[]>([]);
  const [selected, setSelected] = useState<InboxItemDetail | null>(null);
  const [reload, setReload] = useState(0);
  const [loading, setLoading] = useState(true);
  const [busy, setBusy] = useState(false);
  const [error, setError] = useState<string>();

  useEffect(() => {
    const request = new AbortController();
    setLoading(true);
    setError(undefined);
    client.list({ ticketingOnly, assignedToMe, topN: 100 }, request.signal)
      .then(setItems)
      .catch((failure: unknown) => {
        if (!request.signal.aborted) {
          setError(failure instanceof Error ? failure.message : "Inbox unavailable.");
        }
      })
      .finally(() => {
        if (!request.signal.aborted) setLoading(false);
      });
    return () => request.abort();
  }, [assignedToMe, client, reload, ticketingOnly]);

  const open = async (inboxItemId: string) => {
    setError(undefined);
    try {
      setSelected(await client.get(inboxItemId));
    } catch (failure) {
      setError(failure instanceof Error ? failure.message : "Item unavailable.");
    }
  };

  const resolveSelected = async () => {
    if (!selected) return;
    setBusy(true);
    setError(undefined);
    try {
      await client.setStatus(selected.inboxItemId, "Resolved");
      setSelected(await client.get(selected.inboxItemId));
      setReload((value) => value + 1);
    } catch (failure) {
      setError(failure instanceof Error ? failure.message : "Status was not changed.");
    } finally {
      setBusy(false);
    }
  };

  return (
    <main>
      <h1>Universal Inbox</h1>
      <fieldset>
        <legend>Visible work</legend>
        <label><input type="checkbox" checked={ticketingOnly} onChange={(event) => setTicketingOnly(event.target.checked)} /> Support tickets only</label>
        <label><input type="checkbox" checked={assignedToMe} onChange={(event) => setAssignedToMe(event.target.checked)} /> Assigned to me</label>
        <button type="button" onClick={() => setReload((value) => value + 1)}>Refresh</button>
      </fieldset>

      {loading && <p role="status">Loading inbox...</p>}
      {error && <p role="alert">{error}</p>}
      {!loading && !error && items.length === 0 && <p>No visible work.</p>}

      <div>
        <ul aria-label="Inbox queue">
          {items.map((item) => (
            <li key={item.inboxItemId}>
              <button type="button" onClick={() => void open(item.inboxItemId)}>
                <strong>{item.ticket ? `${item.ticket.key} - ` : ""}{itemTitle(item)}</strong>
                <span>{item.status} - {item.previewText || "No preview"}</span>
              </button>
            </li>
          ))}
        </ul>

        {selected && (
          <article aria-live="polite">
            <p>{selected.ticket ? `Support ticket ${selected.ticket.key}` : selected.source.sourceType}</p>
            <h2>{selected.subject || selected.source.sourceKey || "Inbox item"}</h2>
            <p>{selected.previewText || "No preview available."}</p>
            {selected.aiSummary && <p><strong>Prepared context:</strong> {selected.aiSummary}</p>}
            <button
              type="button"
              disabled={busy || selected.status === "Resolved" || selected.status === "Closed"}
              onClick={() => void resolveSelected()}
            >
              {busy ? "Saving..." : "Resolve"}
            </button>
            <h3>Activity</h3>
            <ol>
              {selected.activity.map((event) => (
                <li key={event.activityVersion}>
                  <strong>{event.eventType}</strong> {event.summary || "Activity recorded"}
                  <time dateTime={event.createdUtc}>{event.createdUtc}</time>
                </li>
              ))}
            </ol>
          </article>
        )}
      </div>
    </main>
  );
}

export function HeadlessInboxApp({
  accessToken,
  csrfToken,
  authenticatedFetch,
}: HeadlessInboxAuth) {
  const client = useMemo(
    () => createUniversalInboxHttpClient({
      accessToken,
      csrfToken,
      ...(authenticatedFetch ? { fetchImplementation: authenticatedFetch } : {}),
    }),
    [accessToken, authenticatedFetch, csrfToken],
  );
  return <UnstyledHeadlessInbox client={client} />;
}
```

### Exact browser and SQL path

| Purpose | HTTP route | Reviewed procedure |
| --- | --- | --- |
| Top-bar counts | `GET /api/inbox/badge` | `sp_GetInboxBadgeSecured` |
| Queue | `GET /api/inbox/items` | `sp_Inbox_GetQueueSecured` |
| Detail and activity | `GET /api/inbox/items/{inboxItemId}` | `sp_Inbox_GetItemDetailSecured` |
| Read/status/priority/assignment | `PUT /api/inbox/items/{inboxItemId}/human-state` | `sp_Inbox_MarkRead` / `sp_Inbox_SetStatusSecured` |
| Email ticketing setup | `GET /api/inbox/email-channels/ticketing`
`PUT /api/inbox/email-channels/{channelConnectionId}/ticketing` | `sp_Inbox_GetEmailTicketingSettingsSecured` / `sp_Inbox_SetEmailTicketingSecured` |

These identifiers select an already authorized target; none of them establish tenant, user, DataRole, location, queue, or source-record authority. See the [React component catalog](../builder-guide/react-component-catalog.html)  for generated starters and the [headless guide](../builder-guide/headless-application-kit.html)  for the surrounding authentication and proxy boundary.

## Build a professional Universal Inbox dashboard

These six registry-backed presentation blocks let a designer turn the secured Universal Inbox API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/inbox`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/universal-inbox-sample.json`, its executable authenticated page at `pages/first-class/universal-inbox-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Universal Inbox projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Open, unsorted, SLA-risk, assigned, and resolved counts |
| `entity-list` | `core.entity-list` | Newest authorized items requiring attention |
| `progress-list` | `core.progress-list` | Distribution by queue, channel, priority, or ticket state |
| `series-chart` | `core.series-chart` | Received, assigned, replied-to, and resolved work |
| `data-grid` | `core.presentation-grid` | One bounded page of display-ready Inbox and ticket state |
| `timeline` | `core.timeline` | Delivery, triage, assignment, reply, escalation, resolution, and reopen events |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "universal-inbox-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Inbox operations",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "open",
            "label": "Open items",
            "value": 238,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "unsorted",
            "label": "Needs triage",
            "value": 31,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "sla",
            "label": "SLA at risk",
            "value": 8,
            "format": "number",
            "tone": "danger"
          },
          {
            "key": "resolved",
            "label": "Resolved today",
            "value": 74,
            "format": "number",
            "tone": "success"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "universal-inbox-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Items needing attention",
        "hasMore": true,
        "items": [
          {
            "id": "universal-inbox-sample-1",
            "recordId": "universal-inbox-record-1",
            "primary": "SUP-000482 - Login fails after update",
            "secondary": "Email - Priority support queue",
            "status": {
              "key": "needs-response",
              "label": "Needs response",
              "tone": "warning"
            },
            "trailing": "12 min"
          },
          {
            "id": "universal-inbox-sample-2",
            "recordId": "universal-inbox-record-2",
            "primary": "SUP-000482 - Login fails after update - Follow-up",
            "secondary": "Email - Priority support queue - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "universal-inbox-sample-3",
            "recordId": "universal-inbox-record-3",
            "primary": "SUP-000482 - Login fails after update - West region",
            "secondary": "Email - Priority support queue - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "universal-inbox-sample-4",
            "recordId": "universal-inbox-record-4",
            "primary": "SUP-000482 - Login fails after update - Customer response",
            "secondary": "Email - Priority support queue - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "universal-inbox-sample-5",
            "recordId": "universal-inbox-record-5",
            "primary": "SUP-000482 - Login fails after update - Regional operations review with a deliberately long title",
            "secondary": "Email - Priority support queue - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "universal-inbox-sample-6",
            "recordId": "universal-inbox-record-6",
            "primary": "SUP-000482 - Login fails after update - Completed preview",
            "secondary": "Email - Priority support queue - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "universal-inbox-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Open work by queue",
        "items": [
          {
            "key": "support",
            "label": "Technical support",
            "value": 112,
            "maximum": 216,
            "displayValue": "112",
            "tone": "primary",
            "status": {
              "key": "support",
              "label": "Technical support",
              "tone": "primary"
            }
          },
          {
            "key": "success",
            "label": "Customer success",
            "value": 73,
            "maximum": 216,
            "displayValue": "73",
            "tone": "success",
            "status": {
              "key": "success",
              "label": "Customer success",
              "tone": "success"
            }
          },
          {
            "key": "triage",
            "label": "Unsorted",
            "value": 31,
            "maximum": 216,
            "displayValue": "31",
            "tone": "warning",
            "status": {
              "key": "triage",
              "label": "Unsorted",
              "tone": "warning"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "universal-inbox-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Inbox throughput",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Received",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Resolved",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "universal-inbox-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Authorized inbox items",
        "columns": [
          {
            "key": "subject",
            "label": "Subject",
            "type": "text",
            "align": "left"
          },
          {
            "key": "channel",
            "label": "Channel",
            "type": "text",
            "align": "left"
          },
          {
            "key": "queue",
            "label": "Queue",
            "type": "text",
            "align": "left"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "updated",
            "label": "Updated",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "universal-inbox-row-1",
            "recordId": "universal-inbox-record-1",
            "cells": {
              "subject": "SUP-000482 - Login fails after update",
              "channel": "Email",
              "queue": "Technical support",
              "status": {
                "key": "needs-response",
                "label": "Needs response",
                "tone": "warning"
              },
              "updated": "2026-09-04T17:48:00Z"
            }
          },
          {
            "id": "universal-inbox-row-2",
            "recordId": "universal-inbox-record-2",
            "cells": {
              "subject": "SUP-000482 - Login fails after update - Follow-up",
              "channel": "Email",
              "queue": "Technical support",
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "updated": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "universal-inbox-row-3",
            "recordId": "universal-inbox-record-3",
            "cells": {
              "subject": "SUP-000482 - Login fails after update - West region",
              "channel": "Email",
              "queue": "Technical support",
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "updated": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "universal-inbox-row-4",
            "recordId": "universal-inbox-record-4",
            "cells": {
              "subject": "SUP-000482 - Login fails after update - Customer response",
              "channel": "Email",
              "queue": "Technical support",
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "updated": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "universal-inbox-row-5",
            "recordId": "universal-inbox-record-5",
            "cells": {
              "subject": "SUP-000482 - Login fails after update - Regional operations review with a deliberately long title",
              "channel": "Email - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "queue": "Technical support",
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "updated": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "universal-inbox-row-6",
            "recordId": "universal-inbox-record-6",
            "cells": {
              "subject": "SUP-000482 - Login fails after update - Completed preview",
              "channel": "Email",
              "queue": "Technical support",
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "updated": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 238,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "universal-inbox-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Inbox and ticket activity",
        "hasMore": true,
        "items": [
          {
            "id": "universal-inbox-event-1",
            "recordId": "universal-inbox-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Ticket reply received",
            "description": "The customer added diagnostic details to SUP-000482.",
            "actor": "Maya Chen",
            "tone": "primary"
          },
          {
            "id": "universal-inbox-event-2",
            "recordId": "universal-inbox-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Ticket reply received - Follow-up",
            "description": "The customer added diagnostic details to SUP-000482. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "universal-inbox-event-3",
            "recordId": "universal-inbox-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Ticket reply received - West region",
            "description": "The customer added diagnostic details to SUP-000482. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "universal-inbox-event-4",
            "recordId": "universal-inbox-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Ticket reply received - Customer response",
            "description": "The customer added diagnostic details to SUP-000482. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "universal-inbox-event-5",
            "recordId": "universal-inbox-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Ticket reply received - Regional operations review with a deliberately long title",
            "description": "The customer added diagnostic details to SUP-000482. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "universal-inbox-event-6",
            "recordId": "universal-inbox-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Ticket reply received - Completed preview",
            "description": "The customer added diagnostic details to SUP-000482. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface UniversalInboxPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface UniversalInboxPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: UniversalInboxPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function UniversalInboxPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: UniversalInboxPresentationProps) {
  if (error) return <p role="alert">The Universal Inbox presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Universal Inbox presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Universal Inbox</p>
        <h1>Inbox operations</h1>
        <p>Inbound attention, support tickets, queues, SLA state, ownership, and resolution activity.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/inbox`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "universal-inbox-live",
      "_type": "core.universal-inbox",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Create an explicit Unsorted or Triage queue and monitor it. A routing rule should improve ownership, but no outside message should disappear merely because it did not match a rule.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/universal-inbox.html).

---
title: "Checklists & Signoffs"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/checklists-signoffs.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Checklists & Signoffs

Attaches reusable, versioned checklists to authorized records and lets each item require notes, documents, or photos before the completed run enters the existing Workflow signoff path.

## In brief

- **Runtime key:** module.checklists-signoffs
- **Experience:** Evidence-backed work acceptance
- **Security:** Server-enforced

Use Checklists & Signoffs when work must be performed step by step and accepted with reviewable evidence. A run can attach to a ticket, project, work order, or other universal record without copying that record or inventing another approval system.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.checklists-signoffs. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Attaches reusable, versioned checklists to authorized records and lets each item require notes, documents, or photos before the completed run enters the existing Workflow signoff path.

## Key capabilities

- Create reusable versioned templates with ordered required or optional items.
- Attach a template snapshot to any authorized universal record.
- Track up to 1,000 ordered run items with completion actor, time, note, and revision.
- Require one or more native File documents or photos as proof for selected items.
- Calculate bounded progress and refuse submission while required work or evidence is missing.
- Submit exactly one current run to the existing Workflow and Universal Inbox approval path.
- Support rejection, editing, proof replacement, resubmission, approval, and replayable history.
- Reject stale revisions and make duplicate completion, submission, and decision requests idempotent.

## Common uses

- Work-order inspection and closeout proof.
- Project stage-gate and quality checklists.
- Support-ticket diagnostic or escalation checkoffs.
- Safety, compliance, onboarding, handoff, and document-review signoffs.

## How it connects

Runs attach through universal Record relationships. Evidence remains a native File, decisions remain Workflow approval records, reviewer attention remains in Universal Inbox, and activity/audit records preserve the end-to-end chain.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Every list, detail, item update, evidence link/download, submission, and decision derives tenant, user, DataRole, Location, and source-record scope from server identity. Evidence links do not grant File access, and Workflow permissions—not checklist UI state—control signoff authority.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Add `module.checklists-signoffs` to the source-record pages and menus where users perform or review work.
2. Create a versioned template with ordered items, required/optional state, proof type, and responsible role.
3. Grant source-record, checklist action, Workflow approval, File, DataRole, and Location permissions independently.
4. Attach a run to a representative ticket, project, work order, or custom record and complete it with required notes/documents/photos.
5. Test cross-tenant and cross-location denial, stale and duplicate requests, unauthorized file access, reject/edit/replace/resubmit/approve, failure recovery, and a 1,000-item boundary run before publishing.

## Copy/paste the checklist page

The normal choice is the native block. It already provides template creation, record-attached runs, item updates, document/photo proof, submission, and signoff status. Paste this page document into Raw JSON mode:

```
{
  "blocks": [
    {
      "_id": "work-checklists-signoffs",
      "_type": "module.checklists-signoffs",
      "props": {},
      "children": []
    }
  ]
}
```

With empty props, the page loads a bounded first page of checklist runs visible to the signed-in user. On a contextual record page, set `targetRecordId` through the page editor's validated binding to pre-filter and prefill that record. The value remains a query target; the server independently authorizes it.

### Custom unstyled React feed

For custom presentation inside `apps/tenant-runtime/src`, retain the official authenticated API helper and SDK parser and replace only the markup. This read view does not infer edit or approval authority in React:

```
import { useEffect, useState } from "react";
import type {
  ChecklistRunDetail,
  ChecklistRunList,
  ChecklistRunStatus,
} from "@buildwithhq/module-sdk";
import { getChecklistRun, listChecklistRuns } from "./api";

type ChecklistFeedProps = {
  readonly targetRecordId?: string;
};

const statuses: readonly (ChecklistRunStatus | "")[] = [
  "", "Draft", "InProgress", "ReadyForSignoff",
  "Approved", "Rejected", "Cancelled",
];

export function CustomChecklistFeed({ targetRecordId = "" }: ChecklistFeedProps) {
  const [status, setStatus] = useState<ChecklistRunStatus | "">("");
  const [feed, setFeed] = useState<ChecklistRunList | null>(null);
  const [selected, setSelected] = useState<ChecklistRunDetail | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const request = new AbortController();
    setSelected(null);
    setError(null);
    listChecklistRuns(targetRecordId, status, request.signal)
      .then(setFeed)
      .catch((caught: unknown) => {
        if (!(caught instanceof DOMException && caught.name === "AbortError")) {
          setError(caught instanceof Error ? caught.message : "Checklists could not be loaded.");
        }
      });
    return () => request.abort();
  }, [status, targetRecordId]);

  const open = async (checklistRunId: string) => {
    setError(null);
    try {
      setSelected(await getChecklistRun(checklistRunId));
    } catch (caught) {
      setError(caught instanceof Error ? caught.message : "The checklist could not be loaded.");
    }
  };

  return (
    <section className="custom-checklists" aria-labelledby="checklists-title">
      <header>
        <div>
          <p>First-class module</p>
          <h1 id="checklists-title">Checklists &amp; Signoffs</h1>
        </div>
        <label>
          Status
          <select value={status} onChange={(event) => setStatus(event.target.value as ChecklistRunStatus | "")}>
            {statuses.map((value) => <option key={value || "all"} value={value}>{value || "All statuses"}</option>)}
          </select>
        </label>
      </header>

      {error && <p role="alert">{error}</p>}
      {!feed && !error && <p role="status">Loading checklists...</p>}
      {feed && <p>Showing {feed.items.length} of {feed.totalRecords} visible checklist runs</p>}
      {feed?.items.length === 0 && <p>No checklists match this secured view.</p>}

      <ol className="custom-checklists__runs">
        {feed?.items.map((run) => (
          <li key={run.checklistRunId} data-status={run.status}>
            <button type="button" onClick={() => void open(run.checklistRunId)}>
              <span><strong>{run.title}</strong><small>{run.targetTitle}</small></span>
              <span>{run.completedItemCount}/{run.itemCount} complete / {run.status}</span>
            </button>
          </li>
        ))}
      </ol>

      {selected && (
        <article className="custom-checklists__detail" aria-labelledby="checklist-detail-title">
          <button type="button" onClick={() => setSelected(null)}>Close details</button>
          <h2 id="checklist-detail-title">{selected.title}</h2>
          <p>{selected.status} / revision {selected.revision}</p>
          <ol>
            {selected.items.map((item) => (
              <li key={item.checklistRunItemId}>
                <strong>{item.title}</strong>
                <span>{item.status}{item.isRequired ? " / required" : " / optional"}</span>
                {item.responseText && <p>{item.responseText}</p>}
                {item.evidence.length > 0 && (
                  <ul>{item.evidence.map((proof) => <li key={proof.checklistItemEvidenceId}>{proof.proofKind}: {proof.fileName}</li>)}</ul>
                )}
              </li>
            ))}
          </ol>
        </article>
      )}
    </section>
  );
}
```

### Copy/paste write lifecycle

These helpers show the correct order for a proof-backed item: create a versioned template, attach a run to an authorized Record, upload bytes through Files, attach that File as proof, update with the newest item revision, then reload and submit with one stable request ID.

```
import type { ChecklistRunItem } from "@buildwithhq/module-sdk";
import {
  attachChecklistProof,
  createChecklistTemplate,
  getChecklistRun,
  startChecklistRun,
  submitChecklistForSignoff,
  updateChecklistItem,
  uploadFile,
} from "./api";

export const createCloseoutTemplate = () => createChecklistTemplate({
  name: "Work-order closeout",
  description: "Completion requires a site photo.",
  items: [{
    itemKey: "completion-photo",
    title: "Photograph the completed work",
    instructions: "Show the finished work and surrounding area.",
    responseType: "Checkbox",
    isRequired: true,
    evidenceRequirement: "Photo",
    minimumEvidenceCount: 1,
    sortOrder: 0,
  }],
});

export const startCloseout = (targetRecordId: string, checklistTemplateId: string) =>
  startChecklistRun({ targetRecordId, checklistTemplateId, title: "Closeout" });

export async function completeItemWithPhoto(
  item: ChecklistRunItem,
  photo: File,
  caption: string,
  locationId?: string,
) {
  const uploaded = await uploadFile(photo, { description: caption, locationId });
  if (!uploaded.recordId) throw new Error("The Files API did not return a RecordId.");

  const attached = await attachChecklistProof(item.checklistRunItemId, {
    fileRecordId: uploaded.recordId,
    proofKind: "Photo",
    caption,
  });

  return updateChecklistItem(item.checklistRunItemId, {
    expectedRevision: attached.itemRevision ?? item.revision,
    status: "Completed",
    responseText: "Completed with attached photo evidence.",
  });
}

export async function requestSignoff(checklistRunId: string, requestId: string) {
  const current = await getChecklistRun(checklistRunId);
  return submitChecklistForSignoff(checklistRunId, {
    expectedRevision: current.revision,
    requestId,
  });
}
```

Create the `requestId` once with `crypto.randomUUID()` and keep that same value when retrying one logical submission. Generate a new ID only for a genuinely new submit attempt after the run has been edited. The current SDK list helper deliberately retrieves at most the first 100 authorized runs; use the module's bounded server pagination contract when building a larger administrative catalog. Approval and rejection happen through the existing Universal Inbox Workflow approval contract, not by writing checklist status directly.

### Optional starter styling

Import this beside the custom component or replace it entirely. Presentation does not change the authenticated data binding or server authorization:

```
.custom-checklists { width: 100%; max-width: none; }
.custom-checklists > header {
  align-items: end;
  display: flex;
  gap: 1rem;
  justify-content: space-between;
}
.custom-checklists__runs {
  display: grid;
  gap: .75rem;
  list-style: none;
  margin: 1rem 0;
  padding: 0;
}
.custom-checklists__runs > li {
  background: var(--surface, #fff);
  border: 1px solid var(--line, #d8dee8);
  border-radius: .75rem;
}
.custom-checklists__runs button {
  align-items: center;
  background: transparent;
  border: 0;
  color: inherit;
  display: flex;
  gap: 1rem;
  justify-content: space-between;
  padding: 1rem;
  text-align: left;
  width: 100%;
}
.custom-checklists__runs span { display: grid; gap: .25rem; }
.custom-checklists__detail {
  background: var(--surface-muted, #f7f9fc);
  border-radius: .75rem;
  padding: 1rem;
}
@media (max-width: 640px) {
  .custom-checklists > header,
  .custom-checklists__runs button { align-items: stretch; flex-direction: column; }
}
```

### Exact lifecycle and data path

| Purpose | Method and route | Important contract |
| --- | --- | --- |
| List templates | `GET /api/modules/checklists-signoffs/templates` | Active templates visible in the current tenant |
| Create template | `POST /api/modules/checklists-signoffs/templates` | 1–1,000 unique ordered items |
| List runs | `GET /api/modules/checklists-signoffs/runs` | Filter by target/status; maximum 200 rows per page |
| Open run | `GET /api/modules/checklists-signoffs/runs/{checklistRunId}` | Authorized snapshot, items, revisions, and visible proof |
| Attach run | `POST /api/modules/checklists-signoffs/runs` | Target Record must be inside the current create/edit envelope |
| Update item | `PUT /api/modules/checklists-signoffs/items/{checklistRunItemId}` | `expectedRevision` rejects stale edits |
| Upload proof bytes | `POST /api/modules/files/upload` | Files validates size, signature, MIME and storage policy |
| Attach proof | `POST /api/modules/checklists-signoffs/items/{checklistRunItemId}/proof` | File and checklist must share an authorized scope |
| Remove proof | `DELETE /api/modules/checklists-signoffs/proof/{checklistItemEvidenceId}` | Allowed only while the run is editable |
| Request signoff | `POST /api/modules/checklists-signoffs/runs/{checklistRunId}/submit` | Revision-fenced and idempotent by `requestId` |
| Approve/reject | `POST /api/inbox/items/{inboxItemId}/workflow-approval` | Current Inbox activity and Workflow permission are rechecked |

The API derives SaaS, organization, user, DataRoles and locations from verified server identity. Completing an item does not bypass its proof requirement; attaching proof does not grant permission to download that File; and submitting a run does not grant approval authority. The database returns the bounded authorized checklist projection that the component renders.

See the [complete React component catalog](../builder-guide/react-component-catalog.html)  for generated styled and unstyled block exports, or the [headless application guide](../builder-guide/headless-application-kit.html)  when the React application lives outside the BuildWithHQ tenant shell.

## Build a professional Checklists & Signoffs dashboard

These six registry-backed presentation blocks let a designer turn the secured Checklists & Signoffs API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/checklists-signoffs`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/checklists-signoffs-sample.json`, its executable authenticated page at `pages/first-class/checklists-signoffs-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Checklists & Signoffs projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Visible runs, completion, signoff queue, and exceptions |
| `entity-list` | `core.entity-list` | Recent authorized runs and attached business records |
| `progress-list` | `core.progress-list` | Run distribution or item completion |
| `series-chart` | `core.series-chart` | Started, completed, submitted, and approved over time |
| `data-grid` | `core.presentation-grid` | One bounded page of runs with progress and status |
| `timeline` | `core.timeline` | Completion, evidence, submission, rejection, and approval events |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "checklists-signoffs-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Checklist operations",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "visible",
            "label": "Visible runs",
            "value": 84,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "awaiting",
            "label": "Awaiting signoff",
            "value": 9,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "complete",
            "label": "Items complete",
            "value": 72,
            "format": "percent",
            "tone": "success"
          },
          {
            "key": "attention",
            "label": "Need attention",
            "value": 4,
            "format": "number",
            "tone": "danger"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "checklists-signoffs-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Recent checklist runs",
        "hasMore": true,
        "items": [
          {
            "id": "checklists-signoffs-sample-1",
            "recordId": "checklists-signoffs-record-1",
            "primary": "North Wing closeout",
            "secondary": "WO-1048 - 18 of 20 items",
            "status": {
              "key": "ready-for-signoff",
              "label": "Ready for signoff",
              "tone": "warning"
            },
            "trailing": "2 proofs"
          },
          {
            "id": "checklists-signoffs-sample-2",
            "recordId": "checklists-signoffs-record-2",
            "primary": "North Wing closeout - Follow-up",
            "secondary": "WO-1048 - 18 of 20 items - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "checklists-signoffs-sample-3",
            "recordId": "checklists-signoffs-record-3",
            "primary": "North Wing closeout - West region",
            "secondary": "WO-1048 - 18 of 20 items - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "checklists-signoffs-sample-4",
            "recordId": "checklists-signoffs-record-4",
            "primary": "North Wing closeout - Customer response",
            "secondary": "WO-1048 - 18 of 20 items - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "checklists-signoffs-sample-5",
            "recordId": "checklists-signoffs-record-5",
            "primary": "North Wing closeout - Regional operations review with a deliberately long title",
            "secondary": "WO-1048 - 18 of 20 items - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "checklists-signoffs-sample-6",
            "recordId": "checklists-signoffs-record-6",
            "primary": "North Wing closeout - Completed preview",
            "secondary": "WO-1048 - 18 of 20 items - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "checklists-signoffs-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Runs by status",
        "items": [
          {
            "key": "draft",
            "label": "Draft",
            "value": 18,
            "maximum": 84,
            "displayValue": "18",
            "tone": "neutral",
            "status": {
              "key": "draft",
              "label": "Draft",
              "tone": "neutral"
            }
          },
          {
            "key": "active",
            "label": "In progress",
            "value": 41,
            "maximum": 84,
            "displayValue": "41",
            "tone": "primary",
            "status": {
              "key": "active",
              "label": "In progress",
              "tone": "primary"
            }
          },
          {
            "key": "approved",
            "label": "Approved",
            "value": 25,
            "maximum": 84,
            "displayValue": "25",
            "tone": "success",
            "status": {
              "key": "approved",
              "label": "Approved",
              "tone": "success"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "checklists-signoffs-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Checklist throughput",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Runs started",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Runs approved",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "checklists-signoffs-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Visible checklist runs",
        "columns": [
          {
            "key": "checklist",
            "label": "Checklist",
            "type": "text",
            "align": "left"
          },
          {
            "key": "target",
            "label": "Attached record",
            "type": "text",
            "align": "left"
          },
          {
            "key": "progress",
            "label": "Progress",
            "type": "number",
            "align": "right"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "updated",
            "label": "Updated",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "checklists-signoffs-row-1",
            "recordId": "checklists-signoffs-record-1",
            "cells": {
              "checklist": "North Wing closeout",
              "target": "WO-1048",
              "progress": 90,
              "status": {
                "key": "ready",
                "label": "Ready for signoff",
                "tone": "warning"
              },
              "updated": "2026-09-04T17:45:00Z"
            }
          },
          {
            "id": "checklists-signoffs-row-2",
            "recordId": "checklists-signoffs-record-2",
            "cells": {
              "checklist": "North Wing closeout - Follow-up",
              "target": "WO-1048",
              "progress": 91,
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "updated": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "checklists-signoffs-row-3",
            "recordId": "checklists-signoffs-record-3",
            "cells": {
              "checklist": "North Wing closeout - West region",
              "target": "WO-1048",
              "progress": 92,
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "updated": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "checklists-signoffs-row-4",
            "recordId": "checklists-signoffs-record-4",
            "cells": {
              "checklist": "North Wing closeout - Customer response",
              "target": "WO-1048",
              "progress": 93,
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "updated": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "checklists-signoffs-row-5",
            "recordId": "checklists-signoffs-record-5",
            "cells": {
              "checklist": "North Wing closeout - Regional operations review with a deliberately long title",
              "target": "WO-1048 - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "progress": 94,
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "updated": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "checklists-signoffs-row-6",
            "recordId": "checklists-signoffs-record-6",
            "cells": {
              "checklist": "North Wing closeout - Completed preview",
              "target": "WO-1048",
              "progress": 95,
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "updated": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 84,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "checklists-signoffs-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Checklist activity",
        "hasMore": true,
        "items": [
          {
            "id": "checklists-signoffs-event-1",
            "recordId": "checklists-signoffs-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Evidence attached",
            "description": "A closeout photo was attached to item 18.",
            "actor": "Jordan Lee",
            "tone": "success"
          },
          {
            "id": "checklists-signoffs-event-2",
            "recordId": "checklists-signoffs-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Evidence attached - Follow-up",
            "description": "A closeout photo was attached to item 18. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "checklists-signoffs-event-3",
            "recordId": "checklists-signoffs-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Evidence attached - West region",
            "description": "A closeout photo was attached to item 18. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "checklists-signoffs-event-4",
            "recordId": "checklists-signoffs-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Evidence attached - Customer response",
            "description": "A closeout photo was attached to item 18. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "checklists-signoffs-event-5",
            "recordId": "checklists-signoffs-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Evidence attached - Regional operations review with a deliberately long title",
            "description": "A closeout photo was attached to item 18. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "checklists-signoffs-event-6",
            "recordId": "checklists-signoffs-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Evidence attached - Completed preview",
            "description": "A closeout photo was attached to item 18. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface ChecklistsSignoffsPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface ChecklistsSignoffsPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: ChecklistsSignoffsPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function ChecklistsSignoffsPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: ChecklistsSignoffsPresentationProps) {
  if (error) return <p role="alert">The Checklists & Signoffs presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Checklists & Signoffs presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Checklists & Signoffs</p>
        <h1>Checklist operations</h1>
        <p>Completion, evidence, signoff readiness, visible runs, and recent decisions.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/checklists-signoffs`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "checklists-signoffs-live",
      "_type": "module.checklists-signoffs",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Use concise items with explicit proof rules and keep the normal checklist below the hard 1,000-item boundary. Split genuinely different phases into related runs instead of making one checklist behave like an unbounded database table.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/checklists-signoffs.html).

---
title: "GoClaw"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/goclaw.html"
reviewed_at: "2026-09-14"
authority: Official
---

# GoClaw

Adds a dedicated virtual assistant to a user account that researches, summarizes, classifies, drafts, and proposes work without ever receiving more access or action authority than that user.

## In brief

- **Runtime key:** module.goclaw
- **Experience:** Permission-bound AI assistance
- **Security:** Server-enforced

Use GoClaw as the virtual assistant attached to each enabled user account. It helps that person work their permitted Inbox items and business records, but it is not a privileged service account and cannot step outside the user's existing authorization boundary.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.goclaw. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Adds a dedicated virtual assistant to a user account that researches, summarizes, classifies, drafts, and proposes work without ever receiving more access or action authority than that user.

## Key capabilities

- Read only records, fields, locations, and Inbox context the represented user may read—and only when AI access is also allowed.
- Research, classify, summarize, draft replies, and prepare structured next actions.
- Create suggestion batches whose evidence, risk, confidence, required permission, and inputs can be reviewed.
- Route material or customer-facing actions through configured policy or human approval before deterministic execution.
- Respect action budgets, leases, retries, stale-context fences, and idempotent execution.
- Record attribution, approval/refusal, tool/action evidence, results, failures, ratings, and correlation history.

**Surface:** Per-user account assistant. GoClaw is attached to the represented user and remains inside that user's tenant, DataRole, location, record, field, action, and AI-read boundaries.

## Common uses

- Triage and response preparation for permitted Universal Inbox work.
- Account, case, project, support, or operations research and follow-up suggestions.
- A personal daily assistant that reduces preparation work while the user retains decision authority.

## How it connects

GoClaw claims authorized Inbox work, prepares `AiActionSuggestionBatches` and `AiActionSuggestions`, and—after current permission/policy/approval checks—creates `AiActionExecutions` for deterministic executors. It uses native records and the secured AI retrieval plane rather than maintaining a shadow copy of the user's data.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

GoClaw operates on behalf of one user. Its effective access is the intersection of that user's tenant, DataRole, record, field, location, and action permissions with AI-specific `CanAiReadRecords`, secure-field exclusions, tool policy, quotas, approval policy, and the current source/Inbox activity version. The result can be narrower than the user's normal access, never wider.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Enable the assistant for the intended user account and bind it to that user—do not create a wider shared service identity.
2. Select the Inbox queues/channels and record contexts it may prepare, while preserving all normal user and AI-read checks.
3. Configure reviewed action templates, required permissions, authority/approval policy, quotas, and exact behavior/harness versions.
4. Begin with research and drafts; add deterministic actions one at a time with safe error, retry, and idempotency behavior.
5. Test restricted records, secure fields, another location, stale Inbox activity, refused approval, quota exhaustion, and duplicate execution before widening use.

## Copy/paste the native review surface

GoClaw remains an account-level tenant capability, and the same secured approval queue used by the top bar is now also registered as the real `module.goclaw` page block. Use the block in a native Builder page, or use the same reviewed React client integration in a custom/headless shell:

```
import {
  GoClawApprovalQueue,
  createApprovalQueueHttpClient,
} from "@buildwithhq/universal-inbox";
import { getTenantAccessToken, tenantSessionFetch } from "./api";
import { ensureCsrfToken } from "./webSecurity";

const goClawReviewClient = createApprovalQueueHttpClient({
  accessToken: getTenantAccessToken,
  csrfToken: ensureCsrfToken,
  fetchImplementation: tenantSessionFetch,
});

type GoClawReviewSurfaceProps = {
  readonly initialInboxItemId?: string;
  readonly onClose?: () => void;
  readonly onOpenInbox?: (inboxItemId: string) => void;
};

export function GoClawReviewSurface(props: GoClawReviewSurfaceProps) {
  return <GoClawApprovalQueue client={goClawReviewClient} {...props} />;
}
```

Place this at the account shell level, such as an **AI review** top-bar action or a protected route. The package includes its production component CSS and provides the complete review, edit, approve, reject, take-over, retry, stale-context, and source-Inbox behavior.

### Custom unstyled approval queue

If you own the presentation, keep the official `ApprovalQueueClient` and render only the secured rows it returns. This bounded starter loads at most 100 review batches and makes stale lineage visible:

```
import { useEffect, useState } from "react";
import type {
  ApprovalQueueClient,
  ApprovalQueueItem,
} from "@buildwithhq/universal-inbox";

type UnstyledGoClawQueueProps = {
  readonly client: ApprovalQueueClient;
  readonly onSelect: (item: ApprovalQueueItem) => void;
};

const title = (item: ApprovalQueueItem) =>
  item.subject?.trim() || item.summary?.trim() || item.sourceType;

export function UnstyledGoClawQueue({
  client,
  onSelect,
}: UnstyledGoClawQueueProps) {
  const [items, setItems] = useState<readonly ApprovalQueueItem[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const request = new AbortController();
    setLoading(true);
    setError(null);
    client.list(100, request.signal)
      .then(setItems)
      .catch((failure: unknown) => {
        if (!(failure instanceof DOMException && failure.name === "AbortError")) {
          setItems([]);
          setError(failure instanceof Error ? failure.message : "Approval work is unavailable.");
        }
      })
      .finally(() => {
        if (!request.signal.aborted) setLoading(false);
      });
    return () => request.abort();
  }, [client]);

  return (
    <section className="custom-goclaw" aria-busy={loading}>
      <header>
        <p>GoClaw</p>
        <h1>Approval work</h1>
      </header>
      {loading && <p role="status">Loading approval work...</p>}
      {error && <p role="alert">{error}</p>}
      {!loading && !error && items.length === 0 && <p>No secured approval work is available.</p>}
      <ol>
        {items.map((item) => (
          <li key={item.suggestionBatchId} data-stale={item.isStale || undefined}>
            <button type="button" onClick={() => onSelect(item)}>
              <strong>{title(item)}</strong>
              <span>{item.batchStatus} / {item.riskLevel || "Unrated"} risk</span>
              <span>{item.summary || item.previewText || "Prepared AI work"}</span>
              <small>
                Based on activity {item.basedOnActivityVersion};
                current activity {item.activityVersion}
                {item.isStale ? " / stale - prepare again" : ""}
              </small>
            </button>
          </li>
        ))}
      </ol>
    </section>
  );
}
```

### Review and disposition helpers

A custom detail view can edit only the reviewed draft/action inputs and then call the typed client. It never supplies approver, tenant, role, location, or database identity:

```
import type {
  ApprovalQueueClient,
  ApprovalQueueItem,
} from "@buildwithhq/universal-inbox";

type ReviewedActionEdit = {
  readonly aiActionSuggestionId: string;
  readonly suggestedInput: Record<string, unknown>;
};

type ReviewedApproval = {
  readonly reviewNotes?: string;
  readonly editedDraftResponse?: Record<string, unknown>;
  readonly actionEdits?: readonly ReviewedActionEdit[];
};

export async function approveReviewedWork(
  client: ApprovalQueueClient,
  item: ApprovalQueueItem,
  reviewed: ReviewedApproval = {},
) {
  if (item.isStale || item.activityVersion !== item.basedOnActivityVersion) {
    throw new Error("Inbox activity changed. Re-run GoClaw before approving.");
  }
  return client.approve(item.suggestionBatchId, reviewed);
}

export const rejectPreparedWork = (
  client: ApprovalQueueClient,
  item: ApprovalQueueItem,
  notes?: string,
) => client.reject(item.suggestionBatchId, notes);

export const takeOverPreparedWork = (
  client: ApprovalQueueClient,
  item: ApprovalQueueItem,
  notes?: string,
) => client.takeOver(item.suggestionBatchId, notes);

export const requestFreshPreparation = (
  client: ApprovalQueueClient,
  item: ApprovalQueueItem,
  notes?: string,
) => client.retry(item.suggestionBatchId, notes);
```

The browser check is helpful feedback, but the server is authoritative: it rechecks current source access, `CanAiReadRecords`, `inbox.approve`, every proposed action's permission, reviewed action schemas, and `ActivityVersion` inside the transaction. After an ambiguous network failure, reload the queue before repeating a decision.

### Optional starter styling

Use this only with the custom queue. The native component already imports its own production styles:

```
.custom-goclaw { width: 100%; max-width: none; }
.custom-goclaw > header { margin-bottom: 1rem; }
.custom-goclaw > header > * { margin-block: .25rem; }
.custom-goclaw ol {
  display: grid;
  gap: .75rem;
  list-style: none;
  margin: 0;
  padding: 0;
}
.custom-goclaw li {
  border: 1px solid var(--line, #d8dee8);
  border-radius: .75rem;
}
.custom-goclaw li[data-stale="true"] {
  border-color: var(--warning, #b86b00);
}
.custom-goclaw button {
  background: var(--surface, #fff);
  border: 0;
  border-radius: inherit;
  color: inherit;
  display: grid;
  gap: .35rem;
  padding: 1rem;
  text-align: left;
  width: 100%;
}
.custom-goclaw button:hover,
.custom-goclaw button:focus-visible {
  background: var(--surface-muted, #f7f9fc);
}
```

### Exact browser and worker path

| Purpose | Method and route | Important contract |
| --- | --- | --- |
| List review work | `GET /api/goclaw/approvals?top=100` | Returns at most 500 currently authorized batches; the native UI requests 100 |
| Approve reviewed work | `POST /api/goclaw/approvals/{suggestionBatchId}/approve` | Optional review notes, draft edit, and at most 20 reviewed action-input edits |
| Reject proposal | `POST /api/goclaw/approvals/{suggestionBatchId}/reject` | Dismisses pending suggestions and records the human decision |
| Human take-over | `POST /api/goclaw/approvals/{suggestionBatchId}/take-over` | Returns ownership to the current authorized reviewer |
| Prepare again | `POST /api/goclaw/approvals/{suggestionBatchId}/retry` | Invalidates the old batch and queues a fresh fenced planning pass |
| Open source context | `GET /api/inbox/items/{inboxItemId}` | Loads the secured native source projection through Universal Inbox |
| Set authority policy | `PUT /api/goclaw/agents/{goClawAgentId}/authority` | Human account owner with `inbox.approve`; ResearchOnly, ApprovalRequired, or PolicyAuthorizedLowRisk |

The browser never creates arbitrary actions or writes directly to GoClaw tables. Inbound work first becomes a Universal Inbox item. A fenced worker claim loads authorized context, uses the centrally routed model capability, and persists canonical `AiActionSuggestionBatches` plus `AiActionSuggestions`. Approval creates `AiActionExecutions`; deterministic workers lease `GoClawActionQueue` work, recheck lineage and permission, and record the result. Outbound communication still flows through the communications worker.

The current deterministic action templates are `SendConversationReply`, `CreateFollowup`, `LinkRecords`, `PostMessage`, and `UpdateRecordStatus`. Add a new action only with a reviewed input schema, required permission, deterministic executor, idempotency/recovery behavior, and tests.

GoClaw work and its audit lineage live in the routed SaaS database; secured retrieval uses that SaaS's vector database, while the one central Platform Orchestration database resolves model endpoints and aggregates health. The client selects none of those databases.

See [GoClaw in depth](../builder-guide/goclaw-in-depth.html)  for the authority model, the [React component catalog](../builder-guide/react-component-catalog.html)  for the generated native and headless starters, or the [headless application guide](../builder-guide/headless-application-kit.html)  when the React application lives outside the BuildWithHQ tenant shell.

## Build a professional GoClaw dashboard

These six registry-backed presentation blocks let a designer turn the secured GoClaw API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/goclaw/approvals`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/goclaw-sample.json`, its executable authenticated page at `pages/first-class/goclaw-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful GoClaw projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Review backlog, stale work, decisions, and execution success |
| `entity-list` | `core.entity-list` | Current suggestion batches with source and risk |
| `progress-list` | `core.progress-list` | Distribution by risk, state, or action outcome |
| `series-chart` | `core.series-chart` | Prepared, approved, rejected, and executed work over time |
| `data-grid` | `core.presentation-grid` | One bounded page of reviewable batches |
| `timeline` | `core.timeline` | Preparation, human disposition, retry, execution, and failure evidence |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "goclaw-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "GoClaw review center",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "review",
            "label": "Awaiting review",
            "value": 17,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "stale",
            "label": "Stale batches",
            "value": 2,
            "format": "number",
            "tone": "danger"
          },
          {
            "key": "approved",
            "label": "Approved today",
            "value": 26,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "success",
            "label": "Execution success",
            "value": 97.4,
            "format": "percent",
            "tone": "primary"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "goclaw-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Prepared work",
        "hasMore": true,
        "items": [
          {
            "id": "goclaw-sample-1",
            "recordId": "goclaw-record-1",
            "primary": "Draft reply for SUP-000482",
            "secondary": "Universal Inbox - low risk",
            "status": {
              "key": "approval-required",
              "label": "Approval required",
              "tone": "warning"
            },
            "trailing": "3 actions"
          },
          {
            "id": "goclaw-sample-2",
            "recordId": "goclaw-record-2",
            "primary": "Draft reply for SUP-000482 - Follow-up",
            "secondary": "Universal Inbox - low risk - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "goclaw-sample-3",
            "recordId": "goclaw-record-3",
            "primary": "Draft reply for SUP-000482 - West region",
            "secondary": "Universal Inbox - low risk - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "goclaw-sample-4",
            "recordId": "goclaw-record-4",
            "primary": "Draft reply for SUP-000482 - Customer response",
            "secondary": "Universal Inbox - low risk - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "goclaw-sample-5",
            "recordId": "goclaw-record-5",
            "primary": "Draft reply for SUP-000482 - Regional operations review with a deliberately long title",
            "secondary": "Universal Inbox - low risk - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "goclaw-sample-6",
            "recordId": "goclaw-record-6",
            "primary": "Draft reply for SUP-000482 - Completed preview",
            "secondary": "Universal Inbox - low risk - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "goclaw-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Review queue by risk",
        "items": [
          {
            "key": "low",
            "label": "Low risk",
            "value": 11,
            "maximum": 17,
            "displayValue": "11",
            "tone": "success",
            "status": {
              "key": "low",
              "label": "Low risk",
              "tone": "success"
            }
          },
          {
            "key": "medium",
            "label": "Medium risk",
            "value": 5,
            "maximum": 17,
            "displayValue": "5",
            "tone": "warning",
            "status": {
              "key": "medium",
              "label": "Medium risk",
              "tone": "warning"
            }
          },
          {
            "key": "high",
            "label": "High risk",
            "value": 1,
            "maximum": 17,
            "displayValue": "1",
            "tone": "danger",
            "status": {
              "key": "high",
              "label": "High risk",
              "tone": "danger"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "goclaw-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Preparation and execution",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Prepared",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Executed",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "goclaw-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Authorized suggestion batches",
        "columns": [
          {
            "key": "work",
            "label": "Prepared work",
            "type": "text",
            "align": "left"
          },
          {
            "key": "source",
            "label": "Source",
            "type": "text",
            "align": "left"
          },
          {
            "key": "risk",
            "label": "Risk",
            "type": "status",
            "align": "left"
          },
          {
            "key": "status",
            "label": "State",
            "type": "status",
            "align": "left"
          },
          {
            "key": "updated",
            "label": "Updated",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "goclaw-row-1",
            "recordId": "goclaw-record-1",
            "cells": {
              "work": "Draft reply for SUP-000482",
              "source": "Universal Inbox",
              "risk": {
                "key": "low",
                "label": "Low",
                "tone": "success"
              },
              "status": {
                "key": "pending",
                "label": "Awaiting review",
                "tone": "warning"
              },
              "updated": "2026-09-04T17:42:00Z"
            }
          },
          {
            "id": "goclaw-row-2",
            "recordId": "goclaw-record-2",
            "cells": {
              "work": "Draft reply for SUP-000482 - Follow-up",
              "source": "Universal Inbox",
              "risk": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "updated": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "goclaw-row-3",
            "recordId": "goclaw-record-3",
            "cells": {
              "work": "Draft reply for SUP-000482 - West region",
              "source": "Universal Inbox",
              "risk": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "updated": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "goclaw-row-4",
            "recordId": "goclaw-record-4",
            "cells": {
              "work": "Draft reply for SUP-000482 - Customer response",
              "source": "Universal Inbox",
              "risk": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "updated": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "goclaw-row-5",
            "recordId": "goclaw-record-5",
            "cells": {
              "work": "Draft reply for SUP-000482 - Regional operations review with a deliberately long title",
              "source": "Universal Inbox - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "risk": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "updated": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "goclaw-row-6",
            "recordId": "goclaw-record-6",
            "cells": {
              "work": "Draft reply for SUP-000482 - Completed preview",
              "source": "Universal Inbox",
              "risk": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "updated": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 17,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "goclaw-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "GoClaw decisions and outcomes",
        "hasMore": true,
        "items": [
          {
            "id": "goclaw-event-1",
            "recordId": "goclaw-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Suggestion batch prepared",
            "description": "Evidence and three proposed actions are ready for review.",
            "actor": "GoClaw",
            "tone": "primary"
          },
          {
            "id": "goclaw-event-2",
            "recordId": "goclaw-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Suggestion batch prepared - Follow-up",
            "description": "Evidence and three proposed actions are ready for review. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "goclaw-event-3",
            "recordId": "goclaw-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Suggestion batch prepared - West region",
            "description": "Evidence and three proposed actions are ready for review. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "goclaw-event-4",
            "recordId": "goclaw-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Suggestion batch prepared - Customer response",
            "description": "Evidence and three proposed actions are ready for review. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "goclaw-event-5",
            "recordId": "goclaw-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Suggestion batch prepared - Regional operations review with a deliberately long title",
            "description": "Evidence and three proposed actions are ready for review. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "goclaw-event-6",
            "recordId": "goclaw-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Suggestion batch prepared - Completed preview",
            "description": "Evidence and three proposed actions are ready for review. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface GoClawPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface GoClawPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: GoClawPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function GoClawPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: GoClawPresentationProps) {
  if (error) return <p role="alert">The GoClaw presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading GoClaw presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>GoClaw</p>
        <h1>GoClaw review center</h1>
        <p>Prepared work, risk, approval state, execution outcomes, and stale-context visibility.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/goclaw/approvals`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "goclaw-live",
      "_type": "module.goclaw",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Start each assistant with read-only preparation and one narrow approved action. Expand only after acceptance, edit, refusal, and outcome evidence show the behavior is trustworthy.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/goclaw.html).

---
title: "AI Insights"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/ai-insights.html"
reviewed_at: "2026-09-14"
authority: Official
---

# AI Insights

Runs permission-aware AI analysis in the background each day to create prioritized, evidence-backed insights and governed next actions from meaningful changes in authorized business records.

## In brief

- **Runtime key:** module.ai-insights
- **Experience:** Proactive daily findings
- **Security:** Server-enforced

Use AI Insights when the system should look for important changes without waiting for a user to ask. The daily background cycle turns permitted record and knowledge context into a small, prioritized insight feed for the people entitled to see and act on it.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.ai-insights. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Runs permission-aware AI analysis in the background each day to create prioritized, evidence-backed insights and governed next actions from meaningful changes in authorized business records.

## Key capabilities

- Run a durable daily background cycle for configured insight types and source scopes.
- Steer each nightly run with the app's starter directives and the organization's own "look for" directives; the organization owner turns AI Insights on in Account admin > AI Insights.
- Read only AI-eligible records and evidence through tenant, DataRole, field, location, and `CanAiReadRecords` controls.
- Create structured insights with source record, type/category, title, summary, recommended action, priority, confidence, severity, evidence, model/profile provenance, and lifecycle dates.
- Use source version/context fingerprints and current-state checks to avoid repeatedly presenting stale or duplicate findings.
- Deliver each insight only to users who can currently access its source record; losing source access removes the insight from their secured feed.
- Let each user view, pin, snooze, hide, dismiss, or advance an insight without changing another user's personal feed state.
- Turn a recommended next step into a governed action that still requires the current user's action permission and configured policy or approval.

## Common uses

- Daily account risk, opportunity, renewal, follow-up, and customer-health findings.
- Operational exceptions, overdue work, recurring issues, quality changes, and material KPI movement.
- Proactive company-knowledge, case, service, sales, support, or asset insights with evidence links.

## How it connects

The background cycle writes canonical `AiInsights` linked to their source Records and stores supporting evidence separately. The secured Insights feed presents those findings with per-user state. Recommended work may create a governed insight action, workflow, Inbox item, or GoClaw suggestion, but the insight itself is a finding—not authorization to mutate business data.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Insight generation applies the AI-read envelope before model context is assembled. Insight visibility is inherited from the source record and rechecked at read time. Evidence, recommendations, and actions cannot reveal or operate on records, fields, locations, or tools outside the current user's permissions; material execution uses action-specific permission and policy/approval.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Choose one decision users should make from a daily finding and define its source modules, eligible states, evidence, freshness window, and materiality threshold.
2. Select the exact users/roles and AI-readable record scope; normal record access alone does not imply AI eligibility.
3. Configure the daily schedule, model/harness profile, priority/confidence/severity rules, expiry, deduplication/current-context policy, and safe failure behavior.
4. Define the user-facing insight lifecycle and any optional next action as a reviewed, permission-keyed contract with the required approval policy.
5. Test no-change days, changed source context, duplicates, expired findings, revoked source access, restricted fields/locations, model failure/retry, and proposed-action denial.

## Copy/paste the feed

The normal choice is the native block: it already includes the secured list, filters, bounded pagination, detail panel, evidence, and per-user view, pin, snooze, and hide state. Paste this page document into Raw JSON mode:

```
{
  "blocks": [
    {
      "_id": "ai-insights-feed",
      "_type": "module.ai-insights",
      "props": {},
      "children": []
    }
  ]
}
```

The page shell supplies the page heading. The module expands to the available center column; page and shell layout remain yours.

### Custom unstyled React feed

For custom presentation inside `apps/tenant-runtime/src`, keep the official authenticated API helper and SDK contract parser, then replace only the markup. This starter deliberately does not make authorization decisions in React:

```
import { useEffect, useState } from "react";
import type { AiInsightList } from "@buildwithhq/module-sdk";
import { listAiInsights } from "./api";

export function CustomAiInsightsFeed() {
  const [feed, setFeed] = useState<AiInsightList | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const request = new AbortController();
    listAiInsights({ pageNumber: 1, pageSize: 50 }, request.signal)
      .then(setFeed)
      .catch((caught: unknown) => {
        if (!(caught instanceof DOMException && caught.name === "AbortError")) {
          setError(caught instanceof Error ? caught.message : "AI Insights could not be loaded.");
        }
      });
    return () => request.abort();
  }, []);

  if (error) return <p role="alert">{error}</p>;
  if (!feed) return <p role="status">Loading AI Insights...</p>;
  if (!feed.items.length) return <p>No insights match this secured view.</p>;

  return (
    <section className="custom-insights" aria-labelledby="insights-title">
      <header>
        <div>
          <p>First-class module</p>
          <h1 id="insights-title">AI Insights</h1>
        </div>
        <p>{feed.unviewedCount} new / {feed.totalRecords} visible</p>
      </header>
      <ol>
        {feed.items.map((insight) => (
          <li key={insight.insightId} data-unviewed={!insight.hasViewed}>
            <article>
              <p>{insight.insightCategory || insight.insightType}</p>
              <h2>{insight.title}</h2>
              <p>{insight.summary}</p>
              <small>
                {insight.sourceRecordTitle || insight.sourceModuleKey}
                {insight.severity ? ` / ${insight.severity}` : ""}
                {` / Priority ${insight.priorityScore}`}
              </small>
            </article>
          </li>
        ))}
      </ol>
    </section>
  );
}
```

### Optional starter styling

Drop this next to the unstyled component, import it, and replace the design tokens with your own. Removing this CSS does not change data binding or security.

```
.custom-insights { width: 100%; max-width: none; }
.custom-insights > header {
  align-items: end;
  display: flex;
  gap: 1rem;
  justify-content: space-between;
}
.custom-insights ol {
  display: grid;
  gap: .75rem;
  list-style: none;
  margin: 1rem 0 0;
  padding: 0;
}
.custom-insights li {
  background: var(--surface, #fff);
  border: 1px solid var(--line, #d8dee8);
  border-radius: .75rem;
  padding: 1rem;
}
.custom-insights li[data-unviewed="true"] {
  border-left: .3rem solid var(--accent, #3157d5);
}
.custom-insights h2 { margin: .25rem 0 .5rem; }
@media (max-width: 640px) {
  .custom-insights > header { align-items: start; flex-direction: column; }
}
```

### Exact data path

| Purpose | Method and route | Bound |
| --- | --- | --- |
| Feed | `GET /api/modules/ai-insights` | Maximum 200 rows per page |
| Insight and evidence | `GET /api/modules/ai-insights/{insightId}` | Maximum 25 display-safe evidence rows |
| Personal state | `PUT /api/modules/ai-insights/{insightId}/state` | View, pin, snooze, or hide for the signed-in user |

All three routes derive identity on the server and reapply tenant, SaaS app, active-user, DataRole, location, record-read, and `CanAiReadRecords` checks. The detail route omits raw evidence JSON and action payloads. A recommendation is display-only until a separate Workflow or GoClaw action contract authorizes it.

See the [complete React component catalog](../builder-guide/react-component-catalog.html)  for the generated styled and unstyled block exports, or the [headless application guide](../builder-guide/headless-application-kit.html)  when the React application lives outside the BuildWithHQ tenant shell.

## Build a professional AI Insights dashboard

These six registry-backed presentation blocks let a designer turn the secured AI Insights API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/ai-insights`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/ai-insights-sample.json`, its executable authenticated page at `pages/first-class/ai-insights-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful AI Insights projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Visible, unviewed, pinned, severe, and expiring findings |
| `entity-list` | `core.entity-list` | Highest-priority authorized findings and source records |
| `progress-list` | `core.progress-list` | Distribution by state, severity, or category |
| `series-chart` | `core.series-chart` | Generated, viewed, acted-on, and dismissed findings |
| `data-grid` | `core.presentation-grid` | One bounded page with confidence and source context |
| `timeline` | `core.timeline` | Generation, view, pin, snooze, action, dismissal, and expiry |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "ai-insights-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "AI insight center",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "visible",
            "label": "Visible insights",
            "value": 126,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "unviewed",
            "label": "Unviewed",
            "value": 18,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "pinned",
            "label": "Pinned",
            "value": 7,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "high",
            "label": "High severity",
            "value": 5,
            "format": "number",
            "tone": "danger"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "ai-insights-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Priority insights",
        "hasMore": true,
        "items": [
          {
            "id": "ai-insights-sample-1",
            "recordId": "ai-insights-record-1",
            "primary": "Renewal risk increased",
            "secondary": "Northstar account - 91% confidence",
            "status": {
              "key": "high-severity",
              "label": "High severity",
              "tone": "danger"
            },
            "trailing": "91%"
          },
          {
            "id": "ai-insights-sample-2",
            "recordId": "ai-insights-record-2",
            "primary": "Renewal risk increased - Follow-up",
            "secondary": "Northstar account - 91% confidence - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "ai-insights-sample-3",
            "recordId": "ai-insights-record-3",
            "primary": "Renewal risk increased - West region",
            "secondary": "Northstar account - 91% confidence - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "ai-insights-sample-4",
            "recordId": "ai-insights-record-4",
            "primary": "Renewal risk increased - Customer response",
            "secondary": "Northstar account - 91% confidence - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "ai-insights-sample-5",
            "recordId": "ai-insights-record-5",
            "primary": "Renewal risk increased - Regional operations review with a deliberately long title",
            "secondary": "Northstar account - 91% confidence - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "ai-insights-sample-6",
            "recordId": "ai-insights-record-6",
            "primary": "Renewal risk increased - Completed preview",
            "secondary": "Northstar account - 91% confidence - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "ai-insights-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Insights by state",
        "items": [
          {
            "key": "open",
            "label": "Open",
            "value": 62,
            "maximum": 126,
            "displayValue": "62",
            "tone": "warning",
            "status": {
              "key": "open",
              "label": "Open",
              "tone": "warning"
            }
          },
          {
            "key": "progress",
            "label": "In progress",
            "value": 29,
            "maximum": 126,
            "displayValue": "29",
            "tone": "primary",
            "status": {
              "key": "progress",
              "label": "In progress",
              "tone": "primary"
            }
          },
          {
            "key": "acted",
            "label": "Acted on",
            "value": 35,
            "maximum": 126,
            "displayValue": "35",
            "tone": "success",
            "status": {
              "key": "acted",
              "label": "Acted on",
              "tone": "success"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "ai-insights-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Insight outcomes",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Generated",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Acted on",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "ai-insights-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Authorized insights",
        "columns": [
          {
            "key": "insight",
            "label": "Insight",
            "type": "text",
            "align": "left"
          },
          {
            "key": "source",
            "label": "Source",
            "type": "text",
            "align": "left"
          },
          {
            "key": "confidence",
            "label": "Confidence",
            "type": "number",
            "align": "right"
          },
          {
            "key": "severity",
            "label": "Severity",
            "type": "status",
            "align": "left"
          },
          {
            "key": "created",
            "label": "Created",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "ai-insights-row-1",
            "recordId": "ai-insights-record-1",
            "cells": {
              "insight": "Renewal risk increased",
              "source": "Northstar account",
              "confidence": 91,
              "severity": {
                "key": "high",
                "label": "High",
                "tone": "danger"
              },
              "created": "2026-09-04T16:30:00Z"
            }
          },
          {
            "id": "ai-insights-row-2",
            "recordId": "ai-insights-record-2",
            "cells": {
              "insight": "Renewal risk increased - Follow-up",
              "source": "Northstar account",
              "confidence": 92,
              "severity": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "created": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "ai-insights-row-3",
            "recordId": "ai-insights-record-3",
            "cells": {
              "insight": "Renewal risk increased - West region",
              "source": "Northstar account",
              "confidence": 93,
              "severity": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "created": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "ai-insights-row-4",
            "recordId": "ai-insights-record-4",
            "cells": {
              "insight": "Renewal risk increased - Customer response",
              "source": "Northstar account",
              "confidence": 94,
              "severity": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "created": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "ai-insights-row-5",
            "recordId": "ai-insights-record-5",
            "cells": {
              "insight": "Renewal risk increased - Regional operations review with a deliberately long title",
              "source": "Northstar account - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "confidence": 95,
              "severity": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "created": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "ai-insights-row-6",
            "recordId": "ai-insights-record-6",
            "cells": {
              "insight": "Renewal risk increased - Completed preview",
              "source": "Northstar account",
              "confidence": 96,
              "severity": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "created": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 126,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "ai-insights-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Insight activity",
        "hasMore": true,
        "items": [
          {
            "id": "ai-insights-event-1",
            "recordId": "ai-insights-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Insight generated",
            "description": "A new evidence-backed renewal finding is available.",
            "actor": "AI Insights",
            "tone": "primary"
          },
          {
            "id": "ai-insights-event-2",
            "recordId": "ai-insights-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Insight generated - Follow-up",
            "description": "A new evidence-backed renewal finding is available. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "ai-insights-event-3",
            "recordId": "ai-insights-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Insight generated - West region",
            "description": "A new evidence-backed renewal finding is available. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "ai-insights-event-4",
            "recordId": "ai-insights-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Insight generated - Customer response",
            "description": "A new evidence-backed renewal finding is available. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "ai-insights-event-5",
            "recordId": "ai-insights-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Insight generated - Regional operations review with a deliberately long title",
            "description": "A new evidence-backed renewal finding is available. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "ai-insights-event-6",
            "recordId": "ai-insights-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Insight generated - Completed preview",
            "description": "A new evidence-backed renewal finding is available. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface AiInsightsPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface AiInsightsPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: AiInsightsPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function AiInsightsPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: AiInsightsPresentationProps) {
  if (error) return <p role="alert">The AI Insights presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading AI Insights presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>AI Insights</p>
        <h1>AI insight center</h1>
        <p>Prioritized findings, severity, confidence, source context, and governed user actions.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/ai-insights`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "ai-insights-live",
      "_type": "module.ai-insights",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

A daily run should produce a short list worth reading, not summarize every record. Start with one high-value insight type, measure dismissals and acted-on outcomes, and tune thresholds before adding more.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/ai-insights.html).

---
title: "Contacts"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/contacts.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Contacts

Provides a secured contact directory with configurable contact types, search, create/detail experiences, custom fields, relationships, activity, and favorites.

## In brief

- **Runtime key:** module.contacts
- **Experience:** People & organizations
- **Security:** Server-enforced

Use Contacts as the shared people-and-organization foundation for CRM, customer service, projects, field work, portals, sales, and other relationship-driven applications.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.contacts. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Provides a secured contact directory with configurable contact types, search, create/detail experiences, custom fields, relationships, activity, and favorites.

## Key capabilities

- Search and browse only the contacts visible to the current user.
- Create contacts with name, company, email, phone, and configurable type fields.
- Show secured contact detail, custom fields, related records, activity, and favorite state.
- Reuse the same contact identity across other modules instead of creating duplicate people records.

## Common uses

- Customer and prospect directories.
- Members, vendors, partners, or project stakeholders.
- The person/company context behind conversations, events, work orders, files, and cases.

## How it connects

Contacts commonly anchor Conversations, Calendar attendees, Files, Work Orders, CRM records, and portal membership. Typed relationships preserve the role a contact plays without flattening every relationship into the contact row.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Contact lists and details apply SaaS, tenant, DataRole, location, record, and field rules. Create and edit controls appear only when secured responses grant the corresponding capability; hidden or encrypted dynamic fields are not returned.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.contacts` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

### Explicit scope for create helpers

The native create helpers below require the user's current choice of Personal or one eligible DataRole. In a tenant-runtime component, render `RecordCreateScopeSelect allowAll` from `./RecordCreateScopeSelect` and read its submitted form with `readRecordCreateScope`. Pass that choice to the helper; do not infer it from the page, menu, role count, or a default location. When active locations exist, explicitly choose an authorized location or All when permitted; Personal has no location. For a shared-only helper, validate the returned choice is shared and has a DataRole before calling it. The typed choice is a request, and SQL rechecks current authority. Child actions keep their reviewed parent scope. Ordinary edits preserve the loaded scope and revision; moving scope is a separate explicit action.

## Copy/paste the Contacts page

**Pagination:** In the standard Contacts directory, users can choose 10, 25, 50, 100, or 200 rows per page. Set `props.pageSize` to an integer from 1 through 200 in the page block JSON to choose its initial size (default 25); a custom initial size is also added to the selector. A size change restarts at page one and keeps the search text. The choice is local to the mounted page, not a saved user preference. Multi-type composite directories retain their existing combined-list behavior and do not show this selector.

API callers control `pageNumber` and `pageSize` (1–200), browsing up to 5,000 authorized matches for the current filters. Refine the search to find other records. Fast rows are the default (`includeTotal=false`); follow `hasMore` for navigation and do not present an inexact list total as the full directory size. The separate secured count endpoint returns the full authorized total, even above 5,000. See [progressive loading and exact counts](../api/progressive-loading-and-counts.html)  for the executable SDK example, matching filters and cache boundaries. This browsing policy supersedes the earlier full-directory traversal behavior.

The native block is the fastest complete starting point. It supplies the secured directory, search, create, detail, custom-field display, relationship/activity counts, favorites, and normal server pagination. Paste this page document into Raw JSON mode:

```
{
  "blocks": [
    {
      "_id": "contacts-directory",
      "_type": "module.contacts",
      "props": {
        "title": "Customers and partners",
        "singular": "contact",
        "typeLabel": "Relationship",
        "contactTypes": ["Customer", "Prospect", "Partner"]
      },
      "children": []
    }
  ]
}
```

`title`, `singular`, and `typeLabel` change presentation only. `contactTypes` accepts at most eight values and is a bounded convenience for small segmented directories: the native renderer requests the first 100 authorized rows for each configured type, merges duplicates, and sorts the result. For a large directory, omit `contactTypes` and use the native server-paginated list.

### Custom unstyled React directory

For custom presentation inside `apps/tenant-runtime/src`, keep the official authenticated API helpers and SDK parsers and replace only the markup. This example searches and pages on the server; it never downloads an entire directory and then filters it in the browser:

```
import { FormEvent, useEffect, useState } from "react";
import { contactDynamicValue, type ContactDetail, type ContactList } from "@buildwithhq/module-sdk";
import { getContact, listContacts } from "./api";

const emptyContacts: ContactList = {
  contractVersion: 1,
  pageNumber: 1,
  pageSize: 100,
  totalRecords: 0,
  totalPages: 0,
  totalIsExact: false,
  hasMore: false,
  items: [],
};

type UnstyledContactsDirectoryProps = {
  contactType?: string;
};

export function UnstyledContactsDirectory({
  contactType = "",
}: UnstyledContactsDirectoryProps) {
  const [draftSearch, setDraftSearch] = useState("");
  const [search, setSearch] = useState("");
  const [pageNumber, setPageNumber] = useState(1);
  const [result, setResult] = useState<ContactList>(emptyContacts);
  const [selected, setSelected] = useState<ContactDetail | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const controller = new AbortController();
    setLoading(true);
    setError(null);
    listContacts(search, controller.signal, contactType, pageNumber, 100)
      .then(setResult)
      .catch((caught: unknown) => {
        if (!controller.signal.aborted) {
          setError(caught instanceof Error ? caught.message : "Contacts could not be loaded.");
        }
      })
      .finally(() => {
        if (!controller.signal.aborted) setLoading(false);
      });
    return () => controller.abort();
  }, [contactType, pageNumber, search]);

  function submitSearch(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    setPageNumber(1);
    setSearch(draftSearch.trim());
  }

  async function openContact(recordId: string) {
    setError(null);
    try {
      setSelected(await getContact(recordId));
    } catch (caught) {
      setError(caught instanceof Error ? caught.message : "The contact could not be loaded.");
    }
  }

  return (
    <section className="custom-contacts" aria-labelledby="contacts-title" aria-busy={loading}>
      <header>
        <h1 id="contacts-title">Contacts</h1>
        <p>Showing {result.items.length} on this page; {result.totalIsExact ? result.totalRecords : `at least ${result.totalRecords}`} authorized contacts found.</p>
      </header>

      <form role="search" onSubmit={submitSearch}>
        <label>
          Search name, company, email, or phone
          <input value={draftSearch} onChange={(event) => setDraftSearch(event.target.value)} />
        </label>
        <button type="submit" disabled={loading}>Search</button>
      </form>

      {error && <p role="alert">{error}</p>}
      {!loading && result.items.length === 0 && <p>No visible contacts match this search.</p>}

      <ul aria-label="Contact results">
        {result.items.map((contact) => (
          <li key={contact.recordId}>
            <button type="button" onClick={() => void openContact(contact.recordId)}>
              <strong>{contact.title}</strong>
              <span>{contact.email || contact.phone || "No contact channel"}</span>
              <span>{contact.locationName || "All locations"}</span>
              {contact.isFavorite && <span aria-label="Favorite">★</span>}
            </button>
          </li>
        ))}
      </ul>

      <nav aria-label="Contact pages">
        <button
          type="button"
          disabled={loading || result.pageNumber <= 1}
          onClick={() => setPageNumber((page) => page - 1)}
        >Previous</button>
        <span>Page {result.pageNumber}{result.totalIsExact ? ` of ${Math.max(1, result.totalPages)}` : ""}</span>
        <button
          type="button"
          disabled={loading || !result.hasMore}
          onClick={() => setPageNumber((page) => page + 1)}
        >Next</button>
      </nav>

      {selected && (
        <article aria-label="Selected contact">
          <h2>{selected.title}</h2>
          <p>{selected.email || "No email"} · {selected.phone || selected.mobilePhone || "No phone"}</p>
          <p>{selected.relationCount} related records · {selected.activityCount} activity items</p>
          <dl>
            {selected.dynamicFields.map((field) => (
              <div key={field.fieldKey}>
                <dt>{field.fieldLabel}</dt>
                <dd>{contactDynamicValue(field)}</dd>
              </div>
            ))}
          </dl>
        </article>
      )}
    </section>
  );
}
```

### Replacement-safe create and update

Create accepts native fields, an optional authorized location, and at most 200 typed dynamic-field values. Update is intentionally replacement-shaped: omitted native fields become empty. Always rebuild the request from the current secured detail, apply the user's changes, and send the current `updatedUtc`. A stale edit returns `409`; reload before offering a deliberate retry.

```
import type {
  ContactDetail,
  ContactDynamicField,
  ContactDynamicFieldInput,
  ContactWrite,
} from "@buildwithhq/module-sdk";
import { createContact, setContactFavorite, updateContact } from "./api";
import type { RecordCreateScope } from "./RecordCreateScopeSelect";

const dynamicInput = (field: ContactDynamicField): ContactDynamicFieldInput => ({
  fieldKey: field.fieldKey,
  valueText: field.valueText ?? undefined,
  valueInt: field.valueInt ?? undefined,
  valueDecimal: field.valueDecimal ?? undefined,
  valueDateTime: field.valueDateTime ?? undefined,
  valueBool: field.valueBool ?? undefined,
  valueGuid: field.valueGuid ?? undefined,
  valueJson: field.valueJson ?? undefined,
});

export const contactReplacement = (current: ContactDetail): ContactWrite => ({
  expectedUpdatedUtc: current.updatedUtc,
  locationId: current.locationId ?? undefined,
  contactType: current.contactType ?? "",
  firstName: current.firstName ?? "",
  lastName: current.lastName ?? "",
  companyName: current.companyName ?? "",
  email: current.email ?? "",
  phone: current.phone ?? "",
  mobilePhone: current.mobilePhone ?? "",
  address1: current.address1 ?? "",
  address2: current.address2 ?? "",
  city: current.city ?? "",
  stateProvince: current.stateProvince ?? "",
  postalCode: current.postalCode ?? "",
  country: current.country ?? "",
  notes: current.notes ?? "",
  dynamicFields: current.dynamicFields.map(dynamicInput),
});

// Pass the user's current choice from the secured scope selector.
export async function addCustomer(chosenScope: RecordCreateScope) {
  return createContact({
    ...chosenScope,
    contactType: "Customer",
    firstName: "Ada",
    lastName: "Lovelace",
    companyName: "Analytical Engines",
    email: "ada@example.test",
    dynamicFields: [{ fieldKey: "customerTier", valueText: "Gold" }],
  });
}

export async function saveContact(
  current: ContactDetail,
  changes: Omit<ContactWrite, "expectedUpdatedUtc">,
) {
  return updateContact(current.recordId, {
    ...contactReplacement(current),
    ...changes,
    expectedUpdatedUtc: current.updatedUtc,
  });
}

export async function toggleContactFavorite(current: ContactDetail) {
  return setContactFavorite(current.recordId, !current.isFavorite);
}
```

### Optional styling

The unstyled component uses semantic HTML and can inherit a product's own design system. This small layer makes a two-column directory without changing its data behavior:

```
.custom-contacts { width: 100%; max-width: none; }
.custom-contacts form { display: flex; gap: .75rem; align-items: end; }
.custom-contacts form label { flex: 1; }
.custom-contacts input { box-sizing: border-box; width: 100%; }
.custom-contacts ul { list-style: none; margin: 1rem 0; padding: 0; }
.custom-contacts li + li { border-top: 1px solid var(--line, #d8dee8); }
.custom-contacts li > button {
  align-items: start;
  background: transparent;
  border: 0;
  display: grid;
  gap: .25rem;
  padding: .85rem 0;
  text-align: left;
  width: 100%;
}
.custom-contacts nav { display: flex; gap: 1rem; align-items: center; }
@media (min-width: 800px) {
  .custom-contacts { display: grid; grid-template-columns: minmax(18rem, 1fr) minmax(22rem, 2fr); gap: 1.5rem; }
}
```

### Exact lifecycle and data path

| Purpose | Method and route | Contract behavior |
| --- | --- | --- |
| Secured list/search | `GET /api/modules/contacts?search=&contactType=&locationId=&pageNumber=1&pageSize=100` | Search first, then browse up to 5,000 matches; 1–200 rows per page; use `hasMore` for Next |
| Full authorized match count | `GET /api/modules/contacts/count?search=&contactType=&locationId=` | Same filters and security; no 5,000 cap on the total |
| Secured detail | `GET /api/modules/contacts/{recordId}` | Native and visible dynamic fields, relation/activity counts, and personal favorite state |
| Create | `POST /api/modules/contacts` | Requires create permission, an authorized location, and at least one name/company/email/phone value |
| Replace/update | `PUT /api/modules/contacts/{recordId}` | Requires edit permission and the exact `expectedUpdatedUtc`; stale state is 409 |
| Personal favorite | `PUT /api/modules/contacts/{recordId}/favorite` | Current signed-in user's favorite state only |

These routes derive SaaS, account, user, DataRole, and effective location scope from the authenticated server identity. The browser supplies search, filter, page, location, and record targets only. The service executes `sp_Contacts_ListSecured`, `sp_Contacts_GetSecured`, `sp_Contacts_CreateSecured`, `sp_Contacts_UpdateSecured`, and `sp_Contacts_SetFavoriteSecured`; React does not trim a broader SQL result after retrieval.

Validation failures return `400`, permission failures return `403` where disclosure is safe, stale replacements return `409`, and an absent or inaccessible detail target returns the same `404 contacts_not_found` envelope so it cannot be used as a cross-tenant existence oracle.

See the [complete React component catalog](../builder-guide/react-component-catalog.html)  for all generated page blocks and operations, or the [headless application guide](../builder-guide/headless-application-kit.html)  when the React application lives outside the BuildWithHQ tenant shell.

## Build a professional Contacts dashboard

These six registry-backed presentation blocks let a designer turn the secured Contacts API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/contacts`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/contacts-sample.json`, its executable authenticated page at `pages/first-class/contacts-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Contacts projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Visible contacts, new records, companies, and favorites |
| `entity-list` | `core.entity-list` | Recently touched people and organizations |
| `progress-list` | `core.progress-list` | Distribution by contact type, location, or lifecycle |
| `series-chart` | `core.series-chart` | Contact creation and updates over time |
| `data-grid` | `core.presentation-grid` | One server-paged directory with only display fields |
| `timeline` | `core.timeline` | Creation, edits, relationships, favorites, and related work |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "contacts-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Contact overview",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "visible",
            "label": "Visible contacts",
            "value": 1842,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "new",
            "label": "New this month",
            "value": 86,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "companies",
            "label": "Companies",
            "value": 412,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "favorites",
            "label": "Your favorites",
            "value": 23,
            "format": "number",
            "tone": "warning"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "contacts-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Recently updated contacts",
        "hasMore": true,
        "items": [
          {
            "id": "contacts-sample-1",
            "recordId": "contacts-record-1",
            "primary": "Maya Chen",
            "secondary": "Acme Field Services - Customer",
            "status": {
              "key": "active",
              "label": "Active",
              "tone": "success"
            },
            "trailing": "Reno"
          },
          {
            "id": "contacts-sample-2",
            "recordId": "contacts-record-2",
            "primary": "Maya Chen - Follow-up",
            "secondary": "Acme Field Services - Customer - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "contacts-sample-3",
            "recordId": "contacts-record-3",
            "primary": "Maya Chen - West region",
            "secondary": "Acme Field Services - Customer - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "contacts-sample-4",
            "recordId": "contacts-record-4",
            "primary": "Maya Chen - Customer response",
            "secondary": "Acme Field Services - Customer - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "contacts-sample-5",
            "recordId": "contacts-record-5",
            "primary": "Maya Chen - Regional operations review with a deliberately long title",
            "secondary": "Acme Field Services - Customer - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "contacts-sample-6",
            "recordId": "contacts-record-6",
            "primary": "Maya Chen - Completed preview",
            "secondary": "Acme Field Services - Customer - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "contacts-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Contacts by type",
        "items": [
          {
            "key": "customer",
            "label": "Customers",
            "value": 1104,
            "maximum": 1842,
            "displayValue": "1104",
            "tone": "primary",
            "status": {
              "key": "customer",
              "label": "Customers",
              "tone": "primary"
            }
          },
          {
            "key": "prospect",
            "label": "Prospects",
            "value": 521,
            "maximum": 1842,
            "displayValue": "521",
            "tone": "warning",
            "status": {
              "key": "prospect",
              "label": "Prospects",
              "tone": "warning"
            }
          },
          {
            "key": "partner",
            "label": "Partners",
            "value": 217,
            "maximum": 1842,
            "displayValue": "217",
            "tone": "success",
            "status": {
              "key": "partner",
              "label": "Partners",
              "tone": "success"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "contacts-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Contact growth",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Created",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Updated",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "contacts-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Contact directory",
        "columns": [
          {
            "key": "name",
            "label": "Name",
            "type": "text",
            "align": "left"
          },
          {
            "key": "company",
            "label": "Company",
            "type": "text",
            "align": "left"
          },
          {
            "key": "type",
            "label": "Type",
            "type": "status",
            "align": "left"
          },
          {
            "key": "location",
            "label": "Location",
            "type": "text",
            "align": "left"
          },
          {
            "key": "updated",
            "label": "Updated",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "contacts-row-1",
            "recordId": "contacts-record-1",
            "cells": {
              "name": "Maya Chen",
              "company": "Acme Field Services",
              "type": {
                "key": "customer",
                "label": "Customer",
                "tone": "primary"
              },
              "location": "Reno",
              "updated": "2026-09-04T15:12:00Z"
            }
          },
          {
            "id": "contacts-row-2",
            "recordId": "contacts-record-2",
            "cells": {
              "name": "Maya Chen - Follow-up",
              "company": "Acme Field Services",
              "type": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "location": "Reno",
              "updated": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "contacts-row-3",
            "recordId": "contacts-record-3",
            "cells": {
              "name": "Maya Chen - West region",
              "company": "Acme Field Services",
              "type": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "location": "Reno",
              "updated": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "contacts-row-4",
            "recordId": "contacts-record-4",
            "cells": {
              "name": "Maya Chen - Customer response",
              "company": "Acme Field Services",
              "type": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "location": "Reno",
              "updated": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "contacts-row-5",
            "recordId": "contacts-record-5",
            "cells": {
              "name": "Maya Chen - Regional operations review with a deliberately long title",
              "company": "Acme Field Services - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "type": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "location": "Reno",
              "updated": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "contacts-row-6",
            "recordId": "contacts-record-6",
            "cells": {
              "name": "Maya Chen - Completed preview",
              "company": "Acme Field Services",
              "type": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "location": "Reno",
              "updated": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 1842,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "contacts-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Contact activity",
        "hasMore": true,
        "items": [
          {
            "id": "contacts-event-1",
            "recordId": "contacts-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Contact updated",
            "description": "Phone and company details were refreshed.",
            "actor": "Sam Rivera",
            "tone": "neutral"
          },
          {
            "id": "contacts-event-2",
            "recordId": "contacts-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Contact updated - Follow-up",
            "description": "Phone and company details were refreshed. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "contacts-event-3",
            "recordId": "contacts-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Contact updated - West region",
            "description": "Phone and company details were refreshed. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "contacts-event-4",
            "recordId": "contacts-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Contact updated - Customer response",
            "description": "Phone and company details were refreshed. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "contacts-event-5",
            "recordId": "contacts-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Contact updated - Regional operations review with a deliberately long title",
            "description": "Phone and company details were refreshed. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "contacts-event-6",
            "recordId": "contacts-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Contact updated - Completed preview",
            "description": "Phone and company details were refreshed. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface ContactsPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface ContactsPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: ContactsPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function ContactsPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: ContactsPresentationProps) {
  if (error) return <p role="alert">The Contacts presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Contacts presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Contacts</p>
        <h1>Contact overview</h1>
        <p>People and companies, type distribution, locations, engagement, and recent changes.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/contacts`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "contacts-live",
      "_type": "module.contacts",
      "props": {
        "experience": "directory",
        "title": "Contact directory",
        "pageSize": 25
      },
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Define a small contact-type vocabulary and decide whether organizations are contacts, related company records, or both before importing data.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/contacts.html).

---
title: "Work Orders"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/work-orders.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Work Orders

Tracks work requests through a secured lifecycle with number, customer, location, summary, priority, status, assignments, related records, and service evidence.

## In brief

- **Runtime key:** module.work-orders
- **Experience:** Operational work
- **Security:** Server-enforced

Use Work Orders when an app needs accountable operational work that can be created, prioritized, assigned, moved through approved states, and connected to customers or other records.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.work-orders. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Tracks work requests through a secured lifecycle with number, customer, location, summary, priority, status, assignments, related records, and service evidence.

## Key capabilities

- Search and filter work orders by text and status.
- Create work with summary, description, priority, and optional customer context.
- Move work through the supported status lifecycle with optimistic concurrency.
- Assign team members, designate primary responsibility, and expose related-record counts.
- Let the tenant choose whether Work Order payment collection is disabled, optional, required, manual, at creation, or required before completion.
- Show secured payment history and queue idempotent charges against protected, consented payment methods without exposing card or provider secrets.

## Common uses

- Field service and maintenance dispatch.
- Facilities, asset, repair, installation, or inspection follow-up.
- Internal service requests and operational task queues that need a stronger lifecycle than a simple task.

## How it connects

Work Orders compose naturally with Contacts, Calendar, Files, Conversations, Notifications, Record Relations, Record Activity, and the shared tenant payment ledger. Charges remain linked payment records rather than columns or raw processor data copied into Work Orders.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

The service limits rows by SaaS app, tenant, DataRole, and location and separately checks create, transition, assignment, and payment authority. The account owner manages payment policy and external connector references. Collection requires the existing `CanBillRecords` capability plus edit and record scope; customer and assignee identifiers are query/action targets, not proof of access.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.work-orders` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

### Explicit scope for create helpers

The native create helpers below require the user's current choice of Personal or one eligible DataRole. In a tenant-runtime component, render `RecordCreateScopeSelect allowAll` from `./RecordCreateScopeSelect` and read its submitted form with `readRecordCreateScope`. Pass that choice to the helper; do not infer it from the page, menu, role count, or a default location. When active locations exist, explicitly choose an authorized location or All when permitted; Personal has no location. For a shared-only helper, validate the returned choice is shared and has a DataRole before calling it. The typed choice is a request, and SQL rechecks current authority. Child actions keep their reviewed parent scope. Ordinary edits preserve the loaded scope and revision; moving scope is a separate explicit action.

## Copy/paste the Work Orders page

The native block is the complete starting point: secured search and status filters, bounded server pagination, create/detail views, status transitions, assignments, related-record counts, and the permission-aware payment panel. Paste this page document into Raw JSON mode:

```
{
  "blocks": [
    {
      "_id": "operations-work-orders",
      "_type": "module.work-orders",
      "props": {},
      "children": []
    }
  ]
}
```

The native list asks SQL for only 100 authorized rows at a time. Its next-page control follows `hasMore`; it labels `totalRecords` as “at least” while `totalIsExact` is false rather than running a tenant-wide count for every page.

### Custom unstyled React work queue

For custom presentation inside `apps/tenant-runtime/src`, retain the authenticated API helper and SDK parser and replace only the markup. Search, status, location, ordering, and pagination stay in the stored procedure; React receives the page it should display:

```
import { FormEvent, useEffect, useState } from "react";
import {
  workOrderStatuses,
  type WorkOrderDetail,
  type WorkOrderList,
  type WorkOrderStatus,
} from "@buildwithhq/module-sdk";
import { getWorkOrder, listWorkOrders } from "./api";

const emptyWorkOrders: WorkOrderList = {
  contractVersion: 1,
  pageNumber: 1,
  pageSize: 50,
  totalRecords: 0,
  totalPages: 0,
  totalIsExact: true,
  hasMore: false,
  canCreate: false,
  canBill: false,
  items: [],
};

type UnstyledWorkOrderQueueProps = {
  locationId?: string;
};

export function UnstyledWorkOrderQueue({ locationId = "" }: UnstyledWorkOrderQueueProps) {
  const [draftSearch, setDraftSearch] = useState("");
  const [search, setSearch] = useState("");
  const [status, setStatus] = useState<WorkOrderStatus | "">("");
  const [pageNumber, setPageNumber] = useState(1);
  const [result, setResult] = useState<WorkOrderList>(emptyWorkOrders);
  const [selected, setSelected] = useState<WorkOrderDetail | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const controller = new AbortController();
    setLoading(true);
    setError(null);
    listWorkOrders(search, status, controller.signal, pageNumber, 50, locationId)
      .then(setResult)
      .catch((caught: unknown) => {
        if (!controller.signal.aborted) {
          setError(caught instanceof Error ? caught.message : "Work orders could not be loaded.");
        }
      })
      .finally(() => {
        if (!controller.signal.aborted) setLoading(false);
      });
    return () => controller.abort();
  }, [locationId, pageNumber, search, status]);

  function submitSearch(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    setPageNumber(1);
    setSearch(draftSearch.trim());
  }

  async function openWorkOrder(recordId: string) {
    setError(null);
    try {
      setSelected(await getWorkOrder(recordId));
    } catch (caught) {
      setError(caught instanceof Error ? caught.message : "The work order could not be loaded.");
    }
  }

  const totalLabel = result.totalIsExact
    ? `${result.totalRecords} matching work orders`
    : `At least ${result.totalRecords} matching work orders`;

  return (
    <section className="custom-work-orders" aria-labelledby="work-orders-title" aria-busy={loading}>
      <header>
        <h1 id="work-orders-title">Work orders</h1>
        <p>{totalLabel}</p>
      </header>

      <form role="search" onSubmit={submitSearch}>
        <label>
          Search number or summary
          <input value={draftSearch} onChange={(event) => setDraftSearch(event.target.value)} />
        </label>
        <label>
          Status
          <select value={status} onChange={(event) => { setPageNumber(1); setStatus(event.target.value as WorkOrderStatus | ""); }}>
            <option value="">All statuses</option>
            {workOrderStatuses.map((value) => <option key={value}>{value}</option>)}
          </select>
        </label>
        <button type="submit" disabled={loading}>Search</button>
      </form>

      {error && <p role="alert">{error}</p>}
      {!loading && result.items.length === 0 && <p>No visible work orders match these filters.</p>}

      <ul aria-label="Work order results">
        {result.items.map((workOrder) => (
          <li key={workOrder.recordId}>
            <button type="button" onClick={() => void openWorkOrder(workOrder.recordId)}>
              <strong>{workOrder.workOrderNumber} · {workOrder.summary}</strong>
              <span>{workOrder.status} · {workOrder.priority}</span>
              <span>{workOrder.customerName || "No customer"} · {workOrder.locationName || "All locations"}</span>
            </button>
          </li>
        ))}
      </ul>

      <nav aria-label="Work order pages">
        <button type="button" disabled={loading || result.pageNumber <= 1} onClick={() => setPageNumber((page) => page - 1)}>Previous</button>
        <span>Page {result.pageNumber}</span>
        <button type="button" disabled={loading || !result.hasMore} onClick={() => setPageNumber((page) => page + 1)}>Next</button>
      </nav>

      {selected && (
        <article aria-label="Selected work order">
          <h2>{selected.workOrderNumber} · {selected.summary}</h2>
          <p>{selected.description || "No description"}</p>
          <dl>
            <div><dt>Status</dt><dd>{selected.status}</dd></div>
            <div><dt>Priority</dt><dd>{selected.priority}</dd></div>
            <div><dt>Assignments</dt><dd>{selected.assignmentCount}</dd></div>
            <div><dt>Related records</dt><dd>{selected.relationCount}</dd></div>
          </dl>
          <ul aria-label="Assigned team">
            {selected.assignments.map((assignment) => (
              <li key={assignment.workOrderAssignmentId}>
                {assignment.assignedUserName || assignment.assignedUserId} · {assignment.assignmentRole}
                {assignment.isPrimary ? " · Primary" : ""}
              </li>
            ))}
          </ul>
        </article>
      )}
    </section>
  );
}
```

### Replacement-safe work and lifecycle helpers

Create can use a server-generated number. Update replaces the editable work-order fields, so rebuild it from the latest secured detail and include its `updatedUtc`. Status and assignment are separate commands, and each command advances that timestamp. Re-read the detail after every mutation before issuing another command.

```
import type {
  WorkOrderAssignmentRole,
  WorkOrderDetail,
  WorkOrderStatus,
  WorkOrderWrite,
  WorkOrderUpdate,
} from "@buildwithhq/module-sdk";
import {
  assignWorkOrder,
  createWorkOrder,
  setWorkOrderStatus,
  updateWorkOrder,
} from "./api";

import type { RecordCreateScope } from "./RecordCreateScopeSelect";

export const workOrderReplacement = (current: WorkOrderDetail): WorkOrderUpdate => ({
  expectedUpdatedUtc: current.updatedUtc,
  locationId: current.locationId ?? null,
  customerRecordId: current.customerRecordId ?? null,
  summary: current.summary,
  description: current.description ?? "",
  priority: current.priority,
  scheduledStartUtc: current.scheduledStartUtc ?? null,
  scheduledEndUtc: current.scheduledEndUtc ?? null,
});

export async function createRepairWork(chosenScope: RecordCreateScope, customerRecordId?: string) {
  return createWorkOrder({
    ...chosenScope,
    customerRecordId: customerRecordId ?? null,
    summary: "Inspect and repair rooftop unit",
    description: "Confirm fault, record readings, repair, and attach closeout evidence.",
    priority: "High",
  });
}

export async function saveWorkOrder(
  current: WorkOrderDetail,
  changes: Partial<Omit<WorkOrderUpdate, "expectedUpdatedUtc" | "workOrderNumber">>,
) {
  const request: WorkOrderUpdate = {
    ...workOrderReplacement(current),
    ...changes,
    expectedUpdatedUtc: current.updatedUtc,
  };
  return updateWorkOrder(current.recordId, request);
}

export async function moveWorkOrder(current: WorkOrderDetail, status: WorkOrderStatus) {
  return setWorkOrderStatus(current.recordId, {
    expectedUpdatedUtc: current.updatedUtc,
    status,
  });
}

export async function setWorkOrderAssignee(
  current: WorkOrderDetail,
  assignedUserId: string,
  assignmentRole: WorkOrderAssignmentRole,
  isPrimary = false,
  isActive = true,
) {
  return assignWorkOrder(current.recordId, {
    expectedUpdatedUtc: current.updatedUtc,
    assignedUserId,
    assignmentRole,
    isPrimary,
    isActive,
  });
}
```

Choose `customerRecordId` from secured Contacts results and `assignedUserId` from a server-scoped active-user picker. They are action targets, not proof of access: SQL independently checks customer readability, assignee activity, and work-order location compatibility. The server also enforces the allowed transition graph; do not duplicate it as authorization logic in React.

### Reuse the native payment panel

When a custom Work Order detail needs collection, compose the existing panel rather than handling cards or processor secrets. It shows only controls allowed by the current payment policy and user capability:

Amounts in this payment API are currently named and represented in cents. Configure only currencies whose charge amounts use two decimal places; the server rejects JPY, KRW, CLP and other zero-decimal currencies with `tenant_payments_unsupported_currency`. A queued legacy amount in one of those currencies is failed before the worker contacts Stripe.

```
import type { WorkOrderDetail } from "@buildwithhq/module-sdk";
import { TenantPaymentsPanel } from "./TenantPaymentsPanel";

type WorkOrderPaymentsProps = {
  workOrder: WorkOrderDetail;
  reload: () => void;
};

export function WorkOrderPayments({ workOrder, reload }: WorkOrderPaymentsProps) {
  return (
    <TenantPaymentsPanel
      moduleKey="WorkOrders"
      recordId={workOrder.recordId}
      customerRecordId={workOrder.customerRecordId}
      onChanged={reload}
    />
  );
}
```

The panel submits only a protected payment-method identity, integer amount/currency, and a fresh idempotency key. Card numbers, security codes, raw provider tokens, API secrets, and webhook secrets do not enter the browser request. If the tenant policy requires successful payment before completion, an unpaid or still-open charge makes the `Completed` transition return `409`.

### Optional styling

```
.custom-work-orders { width: 100%; max-width: none; }
.custom-work-orders form { display: flex; gap: .75rem; align-items: end; flex-wrap: wrap; }
.custom-work-orders form label { min-width: 12rem; flex: 1; }
.custom-work-orders input,
.custom-work-orders select { box-sizing: border-box; width: 100%; }
.custom-work-orders ul { list-style: none; margin: 1rem 0; padding: 0; }
.custom-work-orders li + li { border-top: 1px solid var(--line, #d8dee8); }
.custom-work-orders li > button {
  background: transparent;
  border: 0;
  display: grid;
  gap: .25rem;
  padding: .85rem 0;
  text-align: left;
  width: 100%;
}
.custom-work-orders nav { align-items: center; display: flex; gap: 1rem; }
.custom-work-orders article {
  background: var(--surface, #fff);
  border: 1px solid var(--line, #d8dee8);
  border-radius: .75rem;
  margin-top: 1rem;
  padding: 1rem;
}
```

### Exact lifecycle and data path

| Purpose | Method and route | Contract behavior |
| --- | --- | --- |
| List/search/filter | `GET /api/modules/work-orders?search=&status=&locationId=&pageNumber=1&pageSize=100` | Stable updated-time ordering; 1–200 rows; `hasMore` plus an exact/lower-bound total |
| Detail | `GET /api/modules/work-orders/{recordId}` | Work fields, customer/location labels, active assignments, and relation count |
| Create | `POST /api/modules/work-orders` | Starts at Requested; server can generate the work-order number |
| Replace/update | `PUT /api/modules/work-orders/{recordId}` | Full editable shape plus exact `expectedUpdatedUtc` |
| Transition | `PUT /api/modules/work-orders/{recordId}/status` | Server-enforced transition graph, edit permission, concurrency, and payment gate |
| Assign/deactivate | `PUT /api/modules/work-orders/{recordId}/assignment` | Technician, Lead, Contractor, or Dispatcher; active/location-compatible tenant user |
| Payment settings | `GET /api/modules/payments/settings` | Returns only allowed management/collection capabilities and safe connector references |
| Payment policy | `PUT /api/modules/payments/settings/WorkOrders` | Account-owner policy for disabled/optional/required collection and timing |
| Save connector references | `PUT /api/modules/payments/connectors` | Protected secret-store references only; no processor secret value |
| Deactivate connector | `DELETE /api/modules/payments/connectors/{connectorId}` | Account-owner operation; existing payment evidence remains |
| Protected methods | `GET /api/modules/payments/methods?customerRecordId={customerRecordId}` | Active, consented, display-safe methods only |
| Payment history | `GET /api/modules/payments/records/{recordId}` | Secured totals, payments, and charge-intent states |
| Queue charge | `POST /api/modules/payments/records/{recordId}/charges` | 202 Accepted; protected method reference and idempotency key |

The Work Orders application service executes `sp_WorkOrders_ListSecured`, `sp_WorkOrders_GetSecured`, `sp_WorkOrders_CreateSecured`, `sp_WorkOrders_UpdateSecured`, `sp_WorkOrders_SetStatusSecured`, and `sp_WorkOrders_AssignSecured`. Identity and routing stay server-owned. SQL selects only the authorized page before the React component renders it.

Validation failures return `400`, permission failures return `403`, absent or inaccessible detail targets share the same `404 work_order_not_found` response, and stale versions, invalid transitions, or a required-payment completion fence return `409`.

See the [complete React component catalog](../builder-guide/react-component-catalog.html)  for all generated page blocks and operations, or the [headless application guide](../builder-guide/headless-application-kit.html)  when the React application lives outside the BuildWithHQ tenant shell.

## Build a professional Work Orders dashboard

These six registry-backed presentation blocks let a designer turn the secured Work Orders API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/work-orders`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/work-orders-sample.json`, its executable authenticated page at `pages/first-class/work-orders-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Work Orders projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Open, due, overdue, completed, and priority counts |
| `entity-list` | `core.entity-list` | Recent authorized work orders and their next action |
| `progress-list` | `core.progress-list` | Distribution by status, priority, owner, or location |
| `series-chart` | `core.series-chart` | Created, started, completed, and closed work over time |
| `data-grid` | `core.presentation-grid` | One bounded page with ownership, state, and due dates |
| `timeline` | `core.timeline` | Create, assign, dispatch, update, evidence, signoff, and completion events |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "work-orders-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Work order command center",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "open",
            "label": "Open work orders",
            "value": 126,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "due",
            "label": "Due today",
            "value": 18,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "overdue",
            "label": "Overdue",
            "value": 7,
            "format": "number",
            "tone": "danger"
          },
          {
            "key": "completed",
            "label": "Completed this week",
            "value": 84,
            "format": "number",
            "tone": "success"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "work-orders-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Recent work orders",
        "hasMore": true,
        "items": [
          {
            "id": "work-orders-sample-1",
            "recordId": "work-orders-record-1",
            "primary": "WO-1048 - North Wing closeout",
            "secondary": "Acme Field Services - Reno",
            "status": {
              "key": "ready-for-signoff",
              "label": "Ready for signoff",
              "tone": "warning"
            },
            "trailing": "Due today"
          },
          {
            "id": "work-orders-sample-2",
            "recordId": "work-orders-record-2",
            "primary": "WO-1048 - North Wing closeout - Follow-up",
            "secondary": "Acme Field Services - Reno - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "work-orders-sample-3",
            "recordId": "work-orders-record-3",
            "primary": "WO-1048 - North Wing closeout - West region",
            "secondary": "Acme Field Services - Reno - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "work-orders-sample-4",
            "recordId": "work-orders-record-4",
            "primary": "WO-1048 - North Wing closeout - Customer response",
            "secondary": "Acme Field Services - Reno - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "work-orders-sample-5",
            "recordId": "work-orders-record-5",
            "primary": "WO-1048 - North Wing closeout - Regional operations review with a deliberately long title",
            "secondary": "Acme Field Services - Reno - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "work-orders-sample-6",
            "recordId": "work-orders-record-6",
            "primary": "WO-1048 - North Wing closeout - Completed preview",
            "secondary": "Acme Field Services - Reno - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "work-orders-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Work orders by status",
        "items": [
          {
            "key": "new",
            "label": "New",
            "value": 21,
            "maximum": 126,
            "displayValue": "21",
            "tone": "neutral",
            "status": {
              "key": "new",
              "label": "New",
              "tone": "neutral"
            }
          },
          {
            "key": "active",
            "label": "In progress",
            "value": 68,
            "maximum": 126,
            "displayValue": "68",
            "tone": "primary",
            "status": {
              "key": "active",
              "label": "In progress",
              "tone": "primary"
            }
          },
          {
            "key": "ready",
            "label": "Ready for signoff",
            "value": 37,
            "maximum": 126,
            "displayValue": "37",
            "tone": "success",
            "status": {
              "key": "ready",
              "label": "Ready for signoff",
              "tone": "success"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "work-orders-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Work order throughput",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Created",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Completed",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "work-orders-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Visible work orders",
        "columns": [
          {
            "key": "number",
            "label": "Work order",
            "type": "text",
            "align": "left"
          },
          {
            "key": "summary",
            "label": "Summary",
            "type": "text",
            "align": "left"
          },
          {
            "key": "assignee",
            "label": "Assignee",
            "type": "text",
            "align": "left"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "due",
            "label": "Due",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "work-orders-row-1",
            "recordId": "work-orders-record-1",
            "cells": {
              "number": "WO-1048",
              "summary": "North Wing closeout",
              "assignee": "Jordan Lee",
              "status": {
                "key": "ready",
                "label": "Ready for signoff",
                "tone": "warning"
              },
              "due": "2026-09-04T23:00:00Z"
            }
          },
          {
            "id": "work-orders-row-2",
            "recordId": "work-orders-record-2",
            "cells": {
              "number": "WO-1048 - Follow-up",
              "summary": "North Wing closeout",
              "assignee": "Jordan Lee",
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "due": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "work-orders-row-3",
            "recordId": "work-orders-record-3",
            "cells": {
              "number": "WO-1048 - West region",
              "summary": "North Wing closeout",
              "assignee": "Jordan Lee",
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "due": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "work-orders-row-4",
            "recordId": "work-orders-record-4",
            "cells": {
              "number": "WO-1048 - Customer response",
              "summary": "North Wing closeout",
              "assignee": "Jordan Lee",
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "due": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "work-orders-row-5",
            "recordId": "work-orders-record-5",
            "cells": {
              "number": "WO-1048 - Regional operations review with a deliberately long title",
              "summary": "North Wing closeout - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "assignee": "Jordan Lee",
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "due": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "work-orders-row-6",
            "recordId": "work-orders-record-6",
            "cells": {
              "number": "WO-1048 - Completed preview",
              "summary": "North Wing closeout",
              "assignee": "Jordan Lee",
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "due": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 126,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "work-orders-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Work order activity",
        "hasMore": true,
        "items": [
          {
            "id": "work-orders-event-1",
            "recordId": "work-orders-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Work order moved to signoff",
            "description": "WO-1048 completed its field checklist and is ready for review.",
            "actor": "Jordan Lee",
            "tone": "success"
          },
          {
            "id": "work-orders-event-2",
            "recordId": "work-orders-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Work order moved to signoff - Follow-up",
            "description": "WO-1048 completed its field checklist and is ready for review. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "work-orders-event-3",
            "recordId": "work-orders-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Work order moved to signoff - West region",
            "description": "WO-1048 completed its field checklist and is ready for review. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "work-orders-event-4",
            "recordId": "work-orders-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Work order moved to signoff - Customer response",
            "description": "WO-1048 completed its field checklist and is ready for review. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "work-orders-event-5",
            "recordId": "work-orders-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Work order moved to signoff - Regional operations review with a deliberately long title",
            "description": "WO-1048 completed its field checklist and is ready for review. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "work-orders-event-6",
            "recordId": "work-orders-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Work order moved to signoff - Completed preview",
            "description": "WO-1048 completed its field checklist and is ready for review. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface WorkOrdersPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface WorkOrdersPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: WorkOrdersPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function WorkOrdersPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: WorkOrdersPresentationProps) {
  if (error) return <p role="alert">The Work Orders presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Work Orders presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Work Orders</p>
        <h1>Work order command center</h1>
        <p>Current workload, priority, ownership, visible records, throughput, and recent field activity.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/work-orders`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "work-orders-live",
      "_type": "module.work-orders",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Start with the smallest useful status model and explicit transition rules. Add industry-specific fields as secured dynamic fields instead of forking the native lifecycle.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/work-orders.html).

---
title: "Reservations"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/reservations.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Reservations

Turns a bookable product purchase into one secured workflow: contact identity, capacity-protected reservation, protected charge, calendar event, tenant-user assignment, resource booking, and scheduled before/after-service follow-up.

## In brief

- **Runtime key:** module.reservations
- **Experience:** Sell, schedule & follow up
- **Security:** Server-enforced

Use Reservations for appointments, classes, tours, consultations, rentals, services, and other products that must be paid for, placed on a calendar, assigned to a tenant user, connected to a customer contact, and followed up consistently.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.reservations. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Turns a bookable product purchase into one secured workflow: contact identity, capacity-protected reservation, protected charge, calendar event, tenant-user assignment, resource booking, and scheduled before/after-service follow-up.

## Key capabilities

- Define bookable products with duration, price/currency, party limits, concurrent capacity, buffers, hold time, and default location, resource, assignee, and follow-up timing.
- Create or safely reuse an authorized Contact and preserve the purchaser's name, email, phone, and notes.
- Create a capacity-protected Reservation and linked Calendar event, with an optional Resource booking and an active tenant user assigned to deliver the service.
- Queue the existing idempotent charge-intent pipeline using a protected payment-method reference; the API never receives card numbers, security codes, processor credentials, or raw payment tokens.
- Keep paid bookings pending and private until the charge worker reports success, then promote the reservation, event, resource, and follow-ups transactionally.
- Track Pending Payment, Requires Action, Confirmed, Checked In, Completed, Cancelled, No Show, and Payment Failed with optimistic concurrency and an audit timeline.
- Schedule separate pre-service and post-service follow-up date/time, recipient email, subject, message, delivery state, attempts, sent time, and outbound-message reference.
- Use idempotency keys to make checkout retries safe and prevent duplicate contacts, charges, calendar events, and reservations.
- Let the tenant account owner choose disabled, optional, or required collection; creation, manual, or completion timing; full or deposit collection; partial-payment rules; currency; minimum charge; and paid-before-completion enforcement.
- Give users with the existing billing capability a secured balance, payment history, charge history, and protected charge action for the reservation record.

## Reservation purchase flow

| Step | Canonical result | Important behavior |
| --- | --- | --- |
| Choose product, time, and assignee | Product + UTC window + eligible tenant user | Call `GET /api/modules/reservations/assignees` with product, start time, and optional location; pass the selected `optionId` as `assignedUserId` to purchase. Duration, buffers, party size, location, and capacity are revalidated inside the transaction. |
| Identify customer | Contact | An authorized exact email match may be reused; otherwise one Contact is created and linked. |
| Reserve service | Reservation + Calendar event + optional Resource booking | A paid event stays a private payment hold until the charge succeeds. |
| Charge | Billing charge intent | The existing worker uses a protected method; retries use the same idempotency key. |
| Confirm and serve | Lifecycle + audit events | Calendar, resource, and follow-up state remains synchronized. |
| Follow up | PreService and PostService jobs | Each has its own time, email, message, attempts, result, and evidence. |

## Tenant API

- `GET/POST /api/modules/reservations/products` lists and manages the catalog.
- `GET /api/modules/reservations` lists a secured schedule window; `GET /api/modules/reservations/{recordId}` returns detail and history.
- `GET /api/modules/reservations/assignees` returns at most 100 eligible tenant users for the selected product, UTC start, and optional location. Use its selected ID as `assignedUserId` in purchase or reschedule; the server rechecks eligibility and conflicts on write.
- `POST /api/modules/reservations/purchase` performs idempotent contact, calendar, reservation, and charge orchestration.
- `PUT /api/modules/reservations/{recordId}/schedule` reschedules with the current revision and a freshly selected assignee. Purchase and reschedule can return `409 reservations_conflict` when capacity, assignee availability, or the revision changes; refresh choices rather than blindly retrying.
- `PUT /api/modules/reservations/{recordId}/status` applies a lifecycle transition.
- `PUT /api/modules/reservations/{recordId}/followups` creates or reschedules a before/after-service follow-up.
- `GET/PUT /api/modules/payments/settings` reads or changes the tenant-owned Reservations and Work Orders policies.
- `GET /api/modules/payments/records/{recordId}` returns the secured balance/history; `POST /api/modules/payments/records/{recordId}/charges` queues an idempotent protected charge.
- `GET /api/modules/payments/methods` lists display-only metadata for active consented methods; connector endpoints accept external secret references, never reusable credentials.

Reservation product prices and tenant payment policies currently use cents. Two-decimal charge currencies such as USD and EUR are supported. JPY, KRW, CLP and other zero-decimal currencies are rejected until the full API, storage and browser amount contract supports their minor units. Product writes return `reservations_unsupported_currency`; payment policy and direct-charge writes return `tenant_payments_unsupported_currency`.

## Common uses

- Paid consultations and professional-service appointments.
- Tours, classes, lessons, events, and capacity-limited sessions.
- Installations, inspections, salon/wellness visits, rentals, and service calls.
- Free appointments that still need contact, calendar, assignment, capacity, and follow-up.

## How it connects

Reservations reuse Contacts, Calendar, Resources, the billing charge-intent/payment ledger, Record Relations, and the communications worker boundary. The Reservation owns lifecycle; payment, contact, calendar, and message records remain canonical and linked instead of copied into a shadow subsystem.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

List/detail access is inherited from secured universal Records. Product management and mutations require current DataRole capability. Locations and contact targets are revalidated in the user's scope; assignees must be active users assigned to the same app and selected location. Product capacity and opt-in consultation/appointment assignee exclusivity are rechecked transactionally on purchase, reschedule, confirmation, and delayed payment success. Existing shared-capacity products remain non-exclusive by default. Identity comes from verified server context. The tenant account owner controls payment policy and connector references; collection requires the existing `CanBillRecords` capability plus record scope. Raw card data and provider credentials are never accepted or persisted by Reservations.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. As the tenant account owner, configure an external payment-connector secret reference and choose separate Reservations and Work Orders collection policies; never add card fields to a page.
2. Add `module.reservations` to an in-SaaS page and place that shared page in each intended user-type menu.
3. Create each product with duration, price, capacity/party rules, buffer, hold, location/resource/assignee, and follow-up timing.
4. Grant existing DataRole, `CanBillRecords`, and location access to users who may view, collect, sell, assign, check in, complete, cancel, or follow up.
5. Exercise free, disabled, optional, required, deposit, manual, and paid-before-completion paths plus idempotent replay, full capacity, payment success/failure/Requires Action, calendar/resource synchronization, and both follow-ups before publishing.

## Copy/paste the complete Reservations experience

The native block is the safest full starting point. It includes the product catalog, sell-and-reserve form, secured schedule, detail, lifecycle actions, follow-ups, linked payment panel, and bounded server pagination. Paste this page document into Raw JSON mode:

```
{
  "blocks": [
    {
      "_id": "reservations-workspace",
      "_type": "module.reservations",
      "props": {},
      "children": []
    }
  ]
}
```

The browser supplies only filters and action targets. SaaS, account, user, DataRole, location scope, billing capability, and database routing come from the authenticated server context.

### Custom unstyled schedule and detail

This component asks SQL for one authorized time window and page. It does not download a tenant's complete schedule and reduce it in React. The window must be positive and no wider than 732 days; the page size is capped at 500.

```
import { FormEvent, useEffect, useMemo, useState } from "react";
import {
  reservationStatuses,
  type ReservationDetail,
  type ReservationList,
  type ReservationStatus,
} from "@buildwithhq/module-sdk";
import { getReservation, listReservations } from "./api";

const emptyResult: ReservationList = {
  contractVersion: 1,
  pageNumber: 1,
  pageSize: 100,
  totalRecords: 0,
  totalPages: 0,
  items: [],
};

type ReservationQueueProps = {
  assignedUserId?: string;
  locationId?: string;
};

export function ReservationQueue({ assignedUserId = "", locationId = "" }: ReservationQueueProps) {
  const window = useMemo(() => ({
    start: new Date(Date.now() - 30 * 86_400_000).toISOString(),
    end: new Date(Date.now() + 365 * 86_400_000).toISOString(),
  }), []);
  const [draftSearch, setDraftSearch] = useState("");
  const [search, setSearch] = useState("");
  const [status, setStatus] = useState<ReservationStatus | "">("");
  const [page, setPage] = useState(1);
  const [result, setResult] = useState<ReservationList>(emptyResult);
  const [selected, setSelected] = useState<ReservationDetail | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    const controller = new AbortController();
    setLoading(true);
    setError(null);
    listReservations(
      window.start, window.end, search, status, controller.signal,
      assignedUserId, locationId, page, 100,
    )
      .then(setResult)
      .catch((caught: unknown) => {
        if (!controller.signal.aborted) {
          setError(caught instanceof Error ? caught.message : "Reservations could not be loaded.");
        }
      })
      .finally(() => { if (!controller.signal.aborted) setLoading(false); });
    return () => controller.abort();
  }, [assignedUserId, locationId, page, search, status, window]);

  function submitSearch(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    setPage(1);
    setSearch(draftSearch.trim());
  }

  async function open(recordId: string) {
    setError(null);
    try { setSelected(await getReservation(recordId)); }
    catch (caught) {
      setError(caught instanceof Error ? caught.message : "The reservation could not be loaded.");
    }
  }

  return <section className="reservation-queue" aria-busy={loading}>
    <h1>Reservations</h1>
    <form role="search" onSubmit={submitSearch}>
      <label>Search<input value={draftSearch} onChange={e => setDraftSearch(e.target.value)} /></label>
      <label>Status<select value={status} onChange={e => { setPage(1); setStatus(e.target.value as ReservationStatus | ""); }}>
        <option value="">All</option>
        {reservationStatuses.map(value => <option key={value}>{value}</option>)}
      </select></label>
      <button disabled={loading}>Search</button>
    </form>
    {error && <p role="alert">{error}</p>}
    <ul>{result.items.map(item => <li key={item.recordId}>
      <button type="button" onClick={() => void open(item.recordId)}>
        <strong>{item.reservationNumber} - {item.productName}</strong>
        <span>{new Date(item.startUtc).toLocaleString()} - {item.contactName}</span>
        <small>{item.status} - {item.partySize} attendee(s)</small>
      </button>
    </li>)}</ul>
    <nav aria-label="Reservation pages">
      <button disabled={loading || result.pageNumber <= 1} onClick={() => setPage(value => value - 1)}>Previous</button>
      <span>Page {result.pageNumber} of {Math.max(1, result.totalPages)} - {result.totalRecords} reservations</span>
      <button disabled={loading || result.pageNumber >= result.totalPages} onClick={() => setPage(value => value + 1)}>Next</button>
    </nav>
    {selected && <article>
      <h2>{selected.reservationNumber} - {selected.productName}</h2>
      <p>{selected.contactName} - {selected.contactEmail || "No email"}</p>
      <p>{selected.status} - {selected.paymentStatus || "No payment required"}</p>
      <h3>Follow-ups</h3>
      <ul>{selected.followups.map(item => <li key={item.reservationFollowupId}>
        {item.followupType}: {new Date(item.scheduledUtc).toLocaleString()} - {item.deliveryStatus}
      </li>)}</ul>
    </article>}
  </section>;
}
```

### Create and update bookable products

Product update is a full optimistic replacement. Start from the current product, preserve every value, apply the deliberate edits, and send its latest `updatedUtc`. Duration is 5–43,200 minutes; buffers 0–10,080; capacity and party size 1–100,000; hold 1–1,440 minutes.

```
import type { ReservationProduct, ReservationProductWrite } from "@buildwithhq/module-sdk";
import { saveReservationProduct } from "./api";

export async function createConsultation(enforceAssigneeExclusivity: boolean) {
  return saveReservationProduct({
    productKey: "consultation",
    productName: "Consultation",
    description: "A one-hour consultation",
    durationMinutes: 60,
    bufferBeforeMinutes: 15,
    bufferAfterMinutes: 15,
    priceCents: 12500,
    currencyCode: "USD",
    concurrentCapacity: 1,
    enforceAssigneeExclusivity,
    maxPartySize: 1,
    holdMinutes: 15,
    preServiceFollowupMinutes: 1440,
    postServiceFollowupMinutes: 1440,
    preServiceSubject: "Your consultation is tomorrow",
    postServiceSubject: "Thank you for meeting with us",
    isActive: true,
  });
}

export const productReplacement = (current: ReservationProduct): ReservationProductWrite => ({
  reservationProductId: current.reservationProductId,
  expectedUpdatedUtc: current.updatedUtc,
  productKey: current.productKey,
  productName: current.productName,
  description: current.description || "",
  durationMinutes: current.durationMinutes,
  bufferBeforeMinutes: current.bufferBeforeMinutes,
  bufferAfterMinutes: current.bufferAfterMinutes,
  priceCents: current.priceCents,
  currencyCode: current.currencyCode,
  concurrentCapacity: current.concurrentCapacity,
  enforceAssigneeExclusivity: current.enforceAssigneeExclusivity,
  maxPartySize: current.maxPartySize,
  defaultLocationId: current.defaultLocationId,
  defaultResourceId: current.defaultResourceId,
  defaultAssignedUserId: current.defaultAssignedUserId,
  holdMinutes: current.holdMinutes,
  preServiceFollowupMinutes: current.preServiceFollowupMinutes,
  postServiceFollowupMinutes: current.postServiceFollowupMinutes,
  preServiceSubject: current.preServiceSubject || "",
  postServiceSubject: current.postServiceSubject || "",
  isActive: current.isActive,
});

export async function changeProductPrice(current: ReservationProduct, priceCents: number) {
  return saveReservationProduct({ ...productReplacement(current), priceCents });
}
```

### Purchase once, retry safely

Generate one idempotency key when checkout begins, persist it with that checkout attempt, and reuse it for ambiguous network retries. Do not create a new key until the user starts a genuinely new purchase. An existing Contact must be in scope; otherwise supply enough contact fields for the transaction to create one. There is no separate promise-of-availability endpoint: purchase is the authoritative transactional capacity check, and a `409` means the client should offer another time.

```
import type { ReservationPurchase } from "@buildwithhq/module-sdk";
import { purchaseReservation } from "./api";

export function beginCheckout(input: Omit<ReservationPurchase, "idempotencyKey">) {
  const idempotencyKey = crypto.randomUUID();
  const request: ReservationPurchase = { ...input, idempotencyKey };

  // Keep `request` in checkout state. Calling retry() again is safe after a timeout.
  return {
    idempotencyKey,
    retry: () => purchaseReservation(request),
  };
}

const checkout = beginCheckout({
  reservationProductId: "PRODUCT-GUID-FROM-LIST",
  startUtc: "2026-10-10T18:00:00.000Z",
  timeZoneId: "America/Los_Angeles",
  partySize: 1,
  assignedUserId: "ACTIVE-TENANT-USER-GUID",
  locationId: "AUTHORIZED-LOCATION-GUID",
  firstName: "Ada",
  lastName: "Lovelace",
  email: "ada@example.test",
  paymentMethodId: "PROTECTED-CONSENTED-METHOD-ID",
  preServiceFollowupUtc: "2026-10-09T18:00:00.000Z",
  preServiceFollowupEmail: "ada@example.test",
  postServiceFollowupUtc: "2026-10-11T18:00:00.000Z",
  postServiceFollowupEmail: "ada@example.test",
});

export const purchase = () => checkout.retry();
```

### Change state and schedule follow-up

Both actions use optimistic concurrency. Re-fetch detail after every successful mutation before enabling another action; never replay an old timestamp automatically. The server enforces the lifecycle and may refuse completion when the tenant payment policy requires a paid balance.

```
import type { ReservationDetail } from "@buildwithhq/module-sdk";
import { getReservation, setReservationStatus, updateReservationFollowup } from "./api";

export async function checkIn(current: ReservationDetail) {
  await setReservationStatus(current.recordId, {
    expectedUpdatedUtc: current.updatedUtc,
    status: "CheckedIn",
  });
  return getReservation(current.recordId);
}

export async function scheduleThankYou(current: ReservationDetail) {
  await updateReservationFollowup(current.recordId, {
    expectedUpdatedUtc: current.updatedUtc,
    followupType: "PostService",
    scheduledUtc: new Date(Date.now() + 86_400_000).toISOString(),
    recipientEmail: current.contactEmail || "",
    subject: "Thank you",
    bodyText: "Thank you for visiting us.",
  });
  return getReservation(current.recordId);
}
```

### Optional starter styling

```
.reservation-queue { width: 100%; max-width: none; }
.reservation-queue form { align-items: end; display: flex; gap: .75rem; }
.reservation-queue form label { flex: 1; }
.reservation-queue input, .reservation-queue select { box-sizing: border-box; width: 100%; }
.reservation-queue > ul { list-style: none; margin: 1rem 0; padding: 0; }
.reservation-queue > ul button { background: transparent; border: 0; display: grid; gap: .25rem; padding: .75rem 0; text-align: left; width: 100%; }
.reservation-queue nav { align-items: center; display: flex; gap: 1rem; }
.reservation-queue article { border: 1px solid var(--line, #d8dee8); margin-top: 1rem; padding: 1rem; }
@media (max-width: 700px) { .reservation-queue form { align-items: stretch; flex-direction: column; } }
```

### Exact data path

| Purpose | Method and route | Stored-procedure contract |
| --- | --- | --- |
| Product catalog | `GET /api/modules/reservations/products` | `sp_ReservationProducts_ListSecured` |
| Create/replace product | `POST /api/modules/reservations/products` | `sp_ReservationProducts_UpsertSecured` |
| Windowed schedule | `GET /api/modules/reservations` | `sp_Reservations_ListSecured`; exact count, 1–500 rows/page |
| Detail/history | `GET /api/modules/reservations/{recordId}` | `sp_Reservations_GetSecured` |
| Transactional purchase | `POST /api/modules/reservations/purchase` | `sp_Reservations_PurchaseSecured` |
| Lifecycle action | `PUT /api/modules/reservations/{recordId}/status` | `sp_Reservations_SetStatusSecured` |
| Follow-up | `PUT /api/modules/reservations/{recordId}/followups` | `sp_ReservationFollowups_UpdateSecured` |

Paid purchases stay in a held/private state until the billing worker reports success; Calendar, Resource, Reservation, and follow-up visibility are promoted together. Payment method identifiers are protected, consented references. Card numbers, security codes, processor credentials, connection strings, and tenant database names never belong in page JSON or React props.

See the [complete React component catalog](../builder-guide/react-component-catalog.html)  for all generated blocks, or the [headless guide](../builder-guide/headless-application-kit.html)  for an application outside the tenant shell.

## Build a professional Reservations dashboard

These six registry-backed presentation blocks let a designer turn the secured Reservations API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/reservations`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/reservations-sample.json`, its executable authenticated page at `pages/first-class/reservations-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Reservations projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Upcoming, confirmed, payment-held, and exception counts |
| `entity-list` | `core.entity-list` | Next authorized appointments with contact and time |
| `progress-list` | `core.progress-list` | Distribution by lifecycle, product, or payment state |
| `series-chart` | `core.series-chart` | Purchases, check-ins, completions, and cancellations |
| `data-grid` | `core.presentation-grid` | One bounded schedule page with protected payment state |
| `timeline` | `core.timeline` | Purchase, payment, confirmation, check-in, completion, and follow-up |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "reservations-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Reservation operations",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "upcoming",
            "label": "Upcoming",
            "value": 64,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "confirmed",
            "label": "Confirmed",
            "value": 48,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "payment",
            "label": "Awaiting payment",
            "value": 7,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "attention",
            "label": "Need attention",
            "value": 3,
            "format": "number",
            "tone": "danger"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "reservations-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Upcoming reservations",
        "hasMore": true,
        "items": [
          {
            "id": "reservations-sample-1",
            "recordId": "reservations-record-1",
            "primary": "Strategy consultation",
            "secondary": "Maya Chen - Sep 8, 10:00 AM",
            "status": {
              "key": "confirmed",
              "label": "Confirmed",
              "tone": "success"
            },
            "trailing": "1 guest"
          },
          {
            "id": "reservations-sample-2",
            "recordId": "reservations-record-2",
            "primary": "Strategy consultation - Follow-up",
            "secondary": "Maya Chen - Sep 8, 10:00 AM - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "reservations-sample-3",
            "recordId": "reservations-record-3",
            "primary": "Strategy consultation - West region",
            "secondary": "Maya Chen - Sep 8, 10:00 AM - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "reservations-sample-4",
            "recordId": "reservations-record-4",
            "primary": "Strategy consultation - Customer response",
            "secondary": "Maya Chen - Sep 8, 10:00 AM - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "reservations-sample-5",
            "recordId": "reservations-record-5",
            "primary": "Strategy consultation - Regional operations review with a deliberately long title",
            "secondary": "Maya Chen - Sep 8, 10:00 AM - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "reservations-sample-6",
            "recordId": "reservations-record-6",
            "primary": "Strategy consultation - Completed preview",
            "secondary": "Maya Chen - Sep 8, 10:00 AM - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "reservations-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Reservations by state",
        "items": [
          {
            "key": "confirmed",
            "label": "Confirmed",
            "value": 48,
            "maximum": 86,
            "displayValue": "48",
            "tone": "success",
            "status": {
              "key": "confirmed",
              "label": "Confirmed",
              "tone": "success"
            }
          },
          {
            "key": "pending",
            "label": "Pending payment",
            "value": 7,
            "maximum": 86,
            "displayValue": "7",
            "tone": "warning",
            "status": {
              "key": "pending",
              "label": "Pending payment",
              "tone": "warning"
            }
          },
          {
            "key": "completed",
            "label": "Completed",
            "value": 31,
            "maximum": 86,
            "displayValue": "31",
            "tone": "primary",
            "status": {
              "key": "completed",
              "label": "Completed",
              "tone": "primary"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "reservations-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Booking activity",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Purchased",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Completed",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "reservations-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Reservation schedule",
        "columns": [
          {
            "key": "service",
            "label": "Service",
            "type": "text",
            "align": "left"
          },
          {
            "key": "contact",
            "label": "Contact",
            "type": "text",
            "align": "left"
          },
          {
            "key": "start",
            "label": "Start",
            "type": "date",
            "align": "left"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "payment",
            "label": "Payment",
            "type": "status",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "reservations-row-1",
            "recordId": "reservations-record-1",
            "cells": {
              "service": "Strategy consultation",
              "contact": "Maya Chen",
              "start": "2026-09-08T17:00:00Z",
              "status": {
                "key": "confirmed",
                "label": "Confirmed",
                "tone": "success"
              },
              "payment": {
                "key": "paid",
                "label": "Paid",
                "tone": "success"
              }
            }
          },
          {
            "id": "reservations-row-2",
            "recordId": "reservations-record-2",
            "cells": {
              "service": "Strategy consultation - Follow-up",
              "contact": "Maya Chen",
              "start": "2026-09-04T15:42:00Z",
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "payment": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              }
            }
          },
          {
            "id": "reservations-row-3",
            "recordId": "reservations-record-3",
            "cells": {
              "service": "Strategy consultation - West region",
              "contact": "Maya Chen",
              "start": "2026-09-04T12:18:00Z",
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "payment": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              }
            }
          },
          {
            "id": "reservations-row-4",
            "recordId": "reservations-record-4",
            "cells": {
              "service": "Strategy consultation - Customer response",
              "contact": "Maya Chen",
              "start": "2026-09-03T21:07:00Z",
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "payment": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              }
            }
          },
          {
            "id": "reservations-row-5",
            "recordId": "reservations-record-5",
            "cells": {
              "service": "Strategy consultation - Regional operations review with a deliberately long title",
              "contact": "Maya Chen - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "start": "2026-09-03T16:31:00Z",
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "payment": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              }
            }
          },
          {
            "id": "reservations-row-6",
            "recordId": "reservations-record-6",
            "cells": {
              "service": "Strategy consultation - Completed preview",
              "contact": "Maya Chen",
              "start": "2026-09-02T19:14:00Z",
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "payment": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              }
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 64,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "reservations-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Reservation lifecycle",
        "hasMore": true,
        "items": [
          {
            "id": "reservations-event-1",
            "recordId": "reservations-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Reservation confirmed",
            "description": "Payment succeeded and the calendar hold was promoted.",
            "actor": "Billing worker",
            "tone": "success"
          },
          {
            "id": "reservations-event-2",
            "recordId": "reservations-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Reservation confirmed - Follow-up",
            "description": "Payment succeeded and the calendar hold was promoted. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "reservations-event-3",
            "recordId": "reservations-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Reservation confirmed - West region",
            "description": "Payment succeeded and the calendar hold was promoted. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "reservations-event-4",
            "recordId": "reservations-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Reservation confirmed - Customer response",
            "description": "Payment succeeded and the calendar hold was promoted. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "reservations-event-5",
            "recordId": "reservations-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Reservation confirmed - Regional operations review with a deliberately long title",
            "description": "Payment succeeded and the calendar hold was promoted. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "reservations-event-6",
            "recordId": "reservations-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Reservation confirmed - Completed preview",
            "description": "Payment succeeded and the calendar hold was promoted. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface ReservationsPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface ReservationsPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: ReservationsPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function ReservationsPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: ReservationsPresentationProps) {
  if (error) return <p role="alert">The Reservations presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Reservations presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Reservations</p>
        <h1>Reservation operations</h1>
        <p>Upcoming services, named consultant availability, booking state, payment readiness, capacity, and follow-up work.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/reservations`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "reservations-live",
      "_type": "module.reservations",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Start with one product and one assigned team. Decide whether capacity counts people or simultaneous services, set realistic buffers and hold time, configure payment separately, and test duplicate checkout, payment failure, Requires Action, cancellation, no-show, and both follow-ups.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/reservations.html).

---
title: "Calendar"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/calendar.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Calendar

Provides secured month/agenda scheduling for events, attendees, resources, reminders, locations, private events, custom fields, relationships, activity, and favorites.

## In brief

- **Runtime key:** module.calendar
- **Experience:** Time & scheduling
- **Security:** Server-enforced

Use Calendar for meetings, appointments, deadlines, visits, resource bookings, and other time-based work that must remain connected to the app's records and permissions.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.calendar. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Provides secured month/agenda scheduling for events, attendees, resources, reminders, locations, private events, custom fields, relationships, activity, and favorites.

## Key capabilities

- Browse monthly event ranges and search visible events.
- Create timed or all-day events with location, reminder, color, and privacy settings.
- Show attendee responses, resource bookings, custom fields, related records, and activity.
- Favorite important events and connect them to customers, projects, work orders, or cases.

## Common uses

- Customer meetings and project milestones.
- Technician visits, inspections, shifts, or resource schedules.
- Renewal dates, campaign launches, approval deadlines, and case hearings.

## How it connects

Events can relate to Contacts, Work Orders, Conversations, Files, and any authorized dynamic record. Resource bookings remain separate records so shared equipment, rooms, or people can be scheduled without embedding availability in page content.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Calendar queries enforce tenant, DataRole, location, and private-event rules. Attendees and related records are independently secured, and event creation/editing requires the corresponding server permission.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.calendar` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

### Explicit scope for create helpers

The native create helpers below require the user's current choice of Personal or one eligible DataRole. In a tenant-runtime component, render `RecordCreateScopeSelect allowAll` from `./RecordCreateScopeSelect` and read its submitted form with `readRecordCreateScope`. Pass that choice to the helper; do not infer it from the page, menu, role count, or a default location. When active locations exist, explicitly choose an authorized location or All when permitted; Personal has no location. For a shared-only helper, validate the returned choice is shared and has a DataRole before calling it. The typed choice is a request, and SQL rechecks current authority. Child actions keep their reviewed parent scope. Ordinary edits preserve the loaded scope and revision; moving scope is a separate explicit action.

## Copy/paste the Calendar page

The native block supplies a secured month agenda, search, event creation, detail, attendees, resource/relation counts, custom fields, private-event handling, and favorites:

```
{
  "blocks": [
    { "_id": "team-calendar", "_type": "module.calendar", "props": {}, "children": [] }
  ]
}
```

### Custom unstyled React calendar

The list route requires an explicit UTC window no wider than 366 days and returns one authorized page of at most 500 events. Location and owner identifiers are filters, not authorization proof.

```
import { FormEvent, useEffect, useMemo, useState } from "react";
import type { CalendarEventDetail, CalendarEventList } from "@buildwithhq/module-sdk";
import { getCalendarEvent, listCalendarEvents } from "./api";

const empty: CalendarEventList = { contractVersion: 1, windowStart: new Date(0).toISOString(), windowEnd: new Date(1).toISOString(), pageNumber: 1, pageSize: 100, totalRecords: 0, totalPages: 0, items: [] };

export function UnstyledCalendar({ locationId = "", ownerUserId = "" }) {
  const window = useMemo(() => {
    const now = new Date();
    return {
      start: new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)).toISOString(),
      end: new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1)).toISOString(),
    };
  }, []);
  const [draft, setDraft] = useState("");
  const [search, setSearch] = useState("");
  const [page, setPage] = useState(1);
  const [result, setResult] = useState<CalendarEventList>(empty);
  const [selected, setSelected] = useState<CalendarEventDetail | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const controller = new AbortController();
    listCalendarEvents(window.start, window.end, search, controller.signal, locationId, ownerUserId, page, 100)
      .then(setResult)
      .catch((caught: unknown) => { if (!controller.signal.aborted) setError(caught instanceof Error ? caught.message : "Calendar could not be loaded."); });
    return () => controller.abort();
  }, [locationId, ownerUserId, page, search, window]);

  function submit(event: FormEvent) { event.preventDefault(); setPage(1); setSearch(draft.trim()); }
  async function open(recordId: string) { setSelected(await getCalendarEvent(recordId)); }

  return <section className="custom-calendar">
    <h1>Calendar</h1>
    <form role="search" onSubmit={submit}><label>Search events<input value={draft} onChange={e => setDraft(e.target.value)} /></label><button>Search</button></form>
    {error && <p role="alert">{error}</p>}
    <ol>{result.items.map(item => <li key={item.recordId}><button onClick={() => void open(item.recordId)}>
      <time dateTime={item.startUtc}>{new Date(item.startUtc).toLocaleString()}</time><strong>{item.title}</strong><span>{item.locationText || item.locationName || "No location"}{item.isPrivate ? " - Private" : ""}</span>
    </button></li>)}</ol>
    <nav aria-label="Calendar pages"><button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button><span>Page {result.pageNumber} of {Math.max(1, result.totalPages)}</span><button disabled={page >= result.totalPages} onClick={() => setPage(value => value + 1)}>Next</button></nav>
    {selected && <article><h2>{selected.title}</h2><p>{selected.description}</p><p>{selected.attendeeCount} attendees - {selected.resourceBookingCount} resources - {selected.relationCount} related records</p><ul>{selected.attendees.map(person => <li key={person.eventAttendeeId}>{person.displayName || person.externalEmail} - {person.responseStatus}</li>)}</ul></article>}
  </section>;
}
```

### Create, replace, and favorite events

Update is a full optimistic replacement. Reconstruct it from current detail and keep its latest `updatedUtc`. The server revalidates location, owner, private-event, dynamic-field, and edit scope.

```
import type { CalendarDynamicField, CalendarEventDetail, CalendarEventWrite } from "@buildwithhq/module-sdk";
import { createCalendarEvent, getCalendarEvent, setCalendarFavorite, updateCalendarEvent } from "./api";
import type { RecordCreateScope } from "./RecordCreateScopeSelect";

const fieldInput = (field: CalendarDynamicField) => ({
  fieldKey: field.fieldKey, valueText: field.valueText ?? undefined, valueInt: field.valueInt ?? undefined,
  valueDecimal: field.valueDecimal ?? undefined, valueDateTime: field.valueDateTime ?? undefined,
  valueBool: field.valueBool ?? undefined, valueGuid: field.valueGuid ?? undefined, valueJson: field.valueJson,
});

export const eventReplacement = (current: CalendarEventDetail): CalendarEventWrite => ({
  expectedUpdatedUtc: current.updatedUtc, title: current.title, description: current.description || "",
  startUtc: current.startUtc, endUtc: current.endUtc, isAllDay: current.isAllDay,
  locationId: current.locationId || undefined, locationText: current.locationText || "",
  ownerUserId: current.ownerUserId || undefined, colorKey: current.colorKey || "",
  recurrenceRule: current.recurrenceRule || "", recurrenceEnd: current.recurrenceEnd || undefined,
  reminderMinutes: current.reminderMinutes || 0, isPrivate: current.isPrivate,
  videoConferenceUrl: current.videoConferenceUrl || "", dynamicFields: current.dynamicFields.map(fieldInput),
});

export function createPlanningSession(chosenScope: RecordCreateScope, startUtc: string, endUtc: string) {
  return createCalendarEvent({ ...chosenScope, title: "Planning session", startUtc, endUtc, reminderMinutes: 15, isPrivate: false });
}

export async function renameEvent(current: CalendarEventDetail, title: string) {
  await updateCalendarEvent(current.recordId, { ...eventReplacement(current), title });
  return getCalendarEvent(current.recordId);
}

export async function toggleEventFavorite(current: CalendarEventDetail) {
  await setCalendarFavorite(current.recordId, !current.isFavorite);
  return getCalendarEvent(current.recordId);
}
```

### Optional starter styling

```
.custom-calendar { width: 100%; max-width: none; }
.custom-calendar form, .custom-calendar nav { align-items: end; display: flex; gap: .75rem; }
.custom-calendar ol { list-style: none; margin: 1rem 0; padding: 0; }
.custom-calendar li button { background: transparent; border: 0; display: grid; gap: .2rem; padding: .75rem 0; text-align: left; width: 100%; }
.custom-calendar article { border: 1px solid var(--line, #d8dee8); margin-top: 1rem; padding: 1rem; }
```

### Exact data path

| Purpose | Route | Procedure |
| --- | --- | --- |
| Window/list | `GET /api/modules/calendar` | `sp_Calendar_ListSecured` |
| Detail | `GET /api/modules/calendar/{recordId}` | `sp_Calendar_GetSecured` |
| Create | `POST /api/modules/calendar` | `sp_Calendar_CreateSecured` |
| Replace | `PUT /api/modules/calendar/{recordId}` | `sp_Calendar_UpdateSecured` |
| Favorite | `PUT /api/modules/calendar/{recordId}/favorite` | `sp_Calendar_SetFavoriteSecured` |

Attendees and resource bookings shown in detail remain their canonical secured records. This route set does not expose a separate attendee/resource write operation, so a custom page must not invent one. Use Reservations or the owning workflow where those links are created.

## Build a professional Calendar dashboard

These six registry-backed presentation blocks let a designer turn the secured Calendar API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/calendar`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/calendar-sample.json`, its executable authenticated page at `pages/first-class/calendar-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Calendar projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Today, upcoming, response, reminder, and conflict counts |
| `entity-list` | `core.entity-list` | Next visible events with time and location |
| `progress-list` | `core.progress-list` | Attendance, event state, or resource utilization |
| `series-chart` | `core.series-chart` | Created, scheduled, completed, and cancelled events |
| `data-grid` | `core.presentation-grid` | One explicit date-window page of events |
| `timeline` | `core.timeline` | Creation, reschedule, attendance, reminder, resource, and cancellation |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "calendar-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Calendar overview",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "today",
            "label": "Events today",
            "value": 12,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "week",
            "label": "Next 7 days",
            "value": 47,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "responses",
            "label": "Awaiting response",
            "value": 6,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "conflicts",
            "label": "Resource conflicts",
            "value": 1,
            "format": "number",
            "tone": "danger"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "calendar-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Next events",
        "hasMore": true,
        "items": [
          {
            "id": "calendar-sample-1",
            "recordId": "calendar-record-1",
            "primary": "Field team dispatch",
            "secondary": "Sep 5, 8:30 AM - Las Vegas",
            "status": {
              "key": "confirmed",
              "label": "Confirmed",
              "tone": "success"
            },
            "trailing": "8 attendees"
          },
          {
            "id": "calendar-sample-2",
            "recordId": "calendar-record-2",
            "primary": "Field team dispatch - Follow-up",
            "secondary": "Sep 5, 8:30 AM - Las Vegas - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "calendar-sample-3",
            "recordId": "calendar-record-3",
            "primary": "Field team dispatch - West region",
            "secondary": "Sep 5, 8:30 AM - Las Vegas - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "calendar-sample-4",
            "recordId": "calendar-record-4",
            "primary": "Field team dispatch - Customer response",
            "secondary": "Sep 5, 8:30 AM - Las Vegas - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "calendar-sample-5",
            "recordId": "calendar-record-5",
            "primary": "Field team dispatch - Regional operations review with a deliberately long title",
            "secondary": "Sep 5, 8:30 AM - Las Vegas - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "calendar-sample-6",
            "recordId": "calendar-record-6",
            "primary": "Field team dispatch - Completed preview",
            "secondary": "Sep 5, 8:30 AM - Las Vegas - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "calendar-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Events by response",
        "items": [
          {
            "key": "accepted",
            "label": "Accepted",
            "value": 34,
            "maximum": 47,
            "displayValue": "34",
            "tone": "success",
            "status": {
              "key": "accepted",
              "label": "Accepted",
              "tone": "success"
            }
          },
          {
            "key": "tentative",
            "label": "Tentative",
            "value": 7,
            "maximum": 47,
            "displayValue": "7",
            "tone": "warning",
            "status": {
              "key": "tentative",
              "label": "Tentative",
              "tone": "warning"
            }
          },
          {
            "key": "pending",
            "label": "No response",
            "value": 6,
            "maximum": 47,
            "displayValue": "6",
            "tone": "neutral",
            "status": {
              "key": "pending",
              "label": "No response",
              "tone": "neutral"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "calendar-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Schedule volume",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Created",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Completed",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "calendar-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Upcoming schedule",
        "columns": [
          {
            "key": "event",
            "label": "Event",
            "type": "text",
            "align": "left"
          },
          {
            "key": "start",
            "label": "Start",
            "type": "date",
            "align": "left"
          },
          {
            "key": "location",
            "label": "Location",
            "type": "text",
            "align": "left"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "attendees",
            "label": "Attendees",
            "type": "number",
            "align": "right"
          }
        ],
        "rows": [
          {
            "id": "calendar-row-1",
            "recordId": "calendar-record-1",
            "cells": {
              "event": "Field team dispatch",
              "start": "2026-09-05T15:30:00Z",
              "location": "Las Vegas",
              "status": {
                "key": "confirmed",
                "label": "Confirmed",
                "tone": "success"
              },
              "attendees": 8
            }
          },
          {
            "id": "calendar-row-2",
            "recordId": "calendar-record-2",
            "cells": {
              "event": "Field team dispatch - Follow-up",
              "start": "2026-09-04T15:42:00Z",
              "location": "Las Vegas",
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "attendees": 9
            }
          },
          {
            "id": "calendar-row-3",
            "recordId": "calendar-record-3",
            "cells": {
              "event": "Field team dispatch - West region",
              "start": "2026-09-04T12:18:00Z",
              "location": "Las Vegas",
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "attendees": 10
            }
          },
          {
            "id": "calendar-row-4",
            "recordId": "calendar-record-4",
            "cells": {
              "event": "Field team dispatch - Customer response",
              "start": "2026-09-03T21:07:00Z",
              "location": "Las Vegas",
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "attendees": 11
            }
          },
          {
            "id": "calendar-row-5",
            "recordId": "calendar-record-5",
            "cells": {
              "event": "Field team dispatch - Regional operations review with a deliberately long title",
              "start": "2026-09-03T16:31:00Z",
              "location": "Las Vegas - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "attendees": 12
            }
          },
          {
            "id": "calendar-row-6",
            "recordId": "calendar-record-6",
            "cells": {
              "event": "Field team dispatch - Completed preview",
              "start": "2026-09-02T19:14:00Z",
              "location": "Las Vegas",
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "attendees": 13
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 12,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "calendar-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Calendar activity",
        "hasMore": true,
        "items": [
          {
            "id": "calendar-event-1",
            "recordId": "calendar-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Attendee accepted",
            "description": "Maya Chen accepted Field team dispatch.",
            "actor": "Maya Chen",
            "tone": "success"
          },
          {
            "id": "calendar-event-2",
            "recordId": "calendar-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Attendee accepted - Follow-up",
            "description": "Maya Chen accepted Field team dispatch. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "calendar-event-3",
            "recordId": "calendar-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Attendee accepted - West region",
            "description": "Maya Chen accepted Field team dispatch. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "calendar-event-4",
            "recordId": "calendar-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Attendee accepted - Customer response",
            "description": "Maya Chen accepted Field team dispatch. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "calendar-event-5",
            "recordId": "calendar-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Attendee accepted - Regional operations review with a deliberately long title",
            "description": "Maya Chen accepted Field team dispatch. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "calendar-event-6",
            "recordId": "calendar-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Attendee accepted - Completed preview",
            "description": "Maya Chen accepted Field team dispatch. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface CalendarPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface CalendarPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: CalendarPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function CalendarPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: CalendarPresentationProps) {
  if (error) return <p role="alert">The Calendar presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Calendar presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Calendar</p>
        <h1>Calendar overview</h1>
        <p>Upcoming events, attendance, resource demand, reminders, and schedule changes.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/calendar`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "calendar-live",
      "_type": "module.calendar",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Decide which dates are true events and which are merely fields. Use Calendar when users need scheduling, attendance, reminders, or resource coordination.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/calendar.html).

---
title: "Files"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/files.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Files

Provides private file upload, download, metadata, tags, record attachments, comments, locks, custom fields, relationships, activity, and favorites without exposing storage coordinates.

## In brief

- **Runtime key:** module.files
- **Experience:** Documents & evidence
- **Security:** Server-enforced

Use Files as the governed document and attachment layer for contracts, photos, manuals, evidence, exports, project artifacts, and other content that belongs beside business records.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.files. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Provides private file upload, download, metadata, tags, record attachments, comments, locks, custom fields, relationships, activity, and favorites without exposing storage coordinates.

## Key capabilities

- Search and filter secured file metadata by name and content type.
- Upload, describe, tag, edit, and privately download authorized files.
- Keep personal files only you can see, up to the per-person limit the organization owner sets within the app's ceiling.
- Attach one file to multiple permitted records without duplicating the binary.
- Show comments, locks, custom fields, relations, activity, and favorite state.

## Common uses

- Customer and project documents.
- Inspection photos, work-order evidence, manuals, and invoices.
- Case evidence, knowledge source files, and signed approvals.

## How it connects

Files attach to canonical Records across Contacts, Work Orders, Conversations, cases, and dynamic modules. AI ingestion may reference approved files through the secured source pipeline while storage keys and provider credentials stay server-only.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Download and upload flow through authenticated backend endpoints. The browser never receives provider credentials, tenant database identity, storage paths, or unrestricted object-store locations; attachment targets are reauthorized independently.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.files` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

## Copy/paste the Files page

The native block includes secured list/search, upload, metadata replacement, detail, tags, locks, attachment links, download, dynamic fields, and favorites:

```
{
  "blocks": [
    { "_id": "secured-files", "_type": "module.files", "props": {}, "children": [] }
  ]
}
```

### Custom unstyled file library

Search, MIME-prefix filtering, location filtering, and paging execute on the server. Detail intentionally contains no storage provider, path, or object key.

```
import { FormEvent, useEffect, useState } from "react";
import type { FileDetail, FileList } from "@buildwithhq/module-sdk";
import { downloadFileContent, getFile, listFiles } from "./api";

const empty: FileList = { contractVersion: 1, pageNumber: 1, pageSize: 100, totalRecords: 0, totalPages: 0, items: [] };

export function UnstyledFileLibrary({ locationId = "" }) {
  const [draft, setDraft] = useState("");
  const [search, setSearch] = useState("");
  const [contentType, setContentType] = useState("");
  const [page, setPage] = useState(1);
  const [result, setResult] = useState<FileList>(empty);
  const [selected, setSelected] = useState<FileDetail | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const controller = new AbortController();
    listFiles(search, contentType, controller.signal, locationId, page, 100)
      .then(setResult)
      .catch((caught: unknown) => { if (!controller.signal.aborted) setError(caught instanceof Error ? caught.message : "Files could not be loaded."); });
    return () => controller.abort();
  }, [contentType, locationId, page, search]);

  function submit(event: FormEvent) { event.preventDefault(); setPage(1); setSearch(draft.trim()); }
  async function open(recordId: string) { setSelected(await getFile(recordId)); }
  async function download(file: FileDetail) {
    const blob = await downloadFileContent(file.recordId);
    const url = URL.createObjectURL(blob);
    const link = document.createElement("a");
    link.href = url; link.download = file.fileName; link.click();
    URL.revokeObjectURL(url);
  }

  return <section className="custom-files">
    <h1>Files</h1>
    <form role="search" onSubmit={submit}><label>Search<input value={draft} onChange={e => setDraft(e.target.value)} /></label><label>Type<select value={contentType} onChange={e => { setPage(1); setContentType(e.target.value); }}><option value="">All</option><option value="image/">Images</option><option value="application/pdf">PDF</option></select></label><button>Search</button></form>
    {error && <p role="alert">{error}</p>}
    <ul>{result.items.map(file => <li key={file.recordId}><button onClick={() => void open(file.recordId)}><strong>{file.fileName}</strong><span>{file.contentType} - {file.sizeBytes} bytes - {file.attachmentCount} attachments</span></button></li>)}</ul>
    <nav aria-label="File pages"><button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button><span>Page {result.pageNumber} of {Math.max(1, result.totalPages)}</span><button disabled={page >= result.totalPages} onClick={() => setPage(value => value + 1)}>Next</button></nav>
    {selected && <article><h2>{selected.fileName}</h2><p>{selected.description}</p><p>{selected.tags.join(", ")}</p><button onClick={() => void download(selected)}>Download</button><h3>Attached to</h3><ul>{selected.attachments.map(link => <li key={link.attachmentId}>{link.sourceTitle} ({link.sourceModuleKey || "record"})</li>)}</ul></article>}
  </section>;
}
```

### Upload, replace metadata, attach, and detach

Upload is multipart and capped at 25 MiB. The backend normalizes the filename and content type, streams through the configured security scanner, validates the measured size, and removes failed storage writes. Browser MIME metadata is never trusted as a security decision.

```
import type { FileDetail, FileDynamicField } from "@buildwithhq/module-sdk";
import { attachFile, detachFile, getFile, setFileFavorite, updateFile, uploadFile } from "./api";

const fieldInput = (field: FileDynamicField) => ({
  fieldKey: field.fieldKey, valueText: field.valueText ?? undefined, valueInt: field.valueInt ?? undefined,
  valueDecimal: field.valueDecimal ?? undefined, valueDateTime: field.valueDateTime ?? undefined,
  valueBool: field.valueBool ?? undefined, valueGuid: field.valueGuid ?? undefined, valueJson: field.valueJson,
});

export function uploadEvidence(file: File, sourceRecordId: string) {
  return uploadFile(file, { description: "Completion evidence", tags: ["evidence"], sourceRecordId, sourceModuleKey: "checklists-signoffs" });
}

export async function renameFile(current: FileDetail, fileName: string) {
  await updateFile(current.recordId, {
    expectedUpdatedUtc: current.updatedUtc, fileName, locationId: current.locationId || undefined,
    description: current.description || "", tags: current.tags, dynamicFields: current.dynamicFields.map(fieldInput),
  });
  return getFile(current.recordId);
}

export async function linkFile(current: FileDetail, targetRecordId: string, targetModuleKey: string) {
  await attachFile(current.recordId, targetRecordId, targetModuleKey);
  return getFile(current.recordId);
}

export async function unlinkFile(current: FileDetail, attachmentId: string) {
  await detachFile(current.recordId, attachmentId);
  return getFile(current.recordId);
}

export async function toggleFileFavorite(current: FileDetail) {
  await setFileFavorite(current.recordId, !current.isFavorite);
  return getFile(current.recordId);
}
```

### Optional starter styling

```
.custom-files { width: 100%; max-width: none; }
.custom-files form, .custom-files nav { align-items: end; display: flex; gap: .75rem; }
.custom-files > ul { list-style: none; margin: 1rem 0; padding: 0; }
.custom-files > ul button { background: transparent; border: 0; display: grid; gap: .25rem; padding: .75rem 0; text-align: left; width: 100%; }
.custom-files article { border: 1px solid var(--line, #d8dee8); margin-top: 1rem; padding: 1rem; }
```

### Exact data path

| Purpose | Route | Procedure/storage behavior |
| --- | --- | --- |
| List/detail | `GET /api/modules/files`, `GET /api/modules/files/{recordId}` | `sp_Files_ListSecured`, `sp_Files_GetSecured` |
| Upload | `POST /api/modules/files/upload` | Scan + private storage + `sp_Files_CreateSecured` |
| Metadata replace | `PUT /api/modules/files/{recordId}` | `sp_Files_UpdateSecured`, optimistic concurrency |
| Attach/detach | `POST/DELETE /api/modules/files/{recordId}/attachments` | `sp_Files_AttachSecured`, `sp_Files_DetachSecured` |
| Download | `GET /api/modules/files/{recordId}/content` | `sp_Files_GetDownloadSecured` authorizes before private streaming |
| Favorite | `PUT /api/modules/files/{recordId}/favorite` | `sp_Files_SetFavoriteSecured` |

Attachment targets are independently reauthorized. A file visible to a user does not make every linked record visible, and a record identifier does not authorize attachment or download.

## Build a professional Files dashboard

These six registry-backed presentation blocks let a designer turn the secured Files API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/files`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/files-sample.json`, its executable authenticated page at `pages/first-class/files-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Files projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Visible, newly uploaded, pending-scan, and blocked counts |
| `entity-list` | `core.entity-list` | Recent authorized documents and photos |
| `progress-list` | `core.progress-list` | Distribution by type, scan state, or attachment use |
| `series-chart` | `core.series-chart` | Upload, scan, download, and link activity |
| `data-grid` | `core.presentation-grid` | One bounded page without storage routes or secrets |
| `timeline` | `core.timeline` | Upload, scan, metadata edit, relation, download, and deletion |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "files-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "File operations",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "visible",
            "label": "Visible files",
            "value": 932,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "uploaded",
            "label": "Uploaded this month",
            "value": 114,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "pending",
            "label": "Scan pending",
            "value": 3,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "blocked",
            "label": "Blocked",
            "value": 1,
            "format": "number",
            "tone": "danger"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "files-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Recent files",
        "hasMore": true,
        "items": [
          {
            "id": "files-sample-1",
            "recordId": "files-record-1",
            "primary": "north-wing-closeout.pdf",
            "secondary": "PDF - 2.4 MB - WO-1048",
            "status": {
              "key": "available",
              "label": "Available",
              "tone": "success"
            },
            "trailing": "2 links"
          },
          {
            "id": "files-sample-2",
            "recordId": "files-record-2",
            "primary": "north-wing-closeout.pdf - Follow-up",
            "secondary": "PDF - 2.4 MB - WO-1048 - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "files-sample-3",
            "recordId": "files-record-3",
            "primary": "north-wing-closeout.pdf - West region",
            "secondary": "PDF - 2.4 MB - WO-1048 - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "files-sample-4",
            "recordId": "files-record-4",
            "primary": "north-wing-closeout.pdf - Customer response",
            "secondary": "PDF - 2.4 MB - WO-1048 - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "files-sample-5",
            "recordId": "files-record-5",
            "primary": "north-wing-closeout.pdf - Regional operations review with a deliberately long title",
            "secondary": "PDF - 2.4 MB - WO-1048 - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "files-sample-6",
            "recordId": "files-record-6",
            "primary": "north-wing-closeout.pdf - Completed preview",
            "secondary": "PDF - 2.4 MB - WO-1048 - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "files-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Files by type",
        "items": [
          {
            "key": "documents",
            "label": "Documents",
            "value": 531,
            "maximum": 932,
            "displayValue": "531",
            "tone": "primary",
            "status": {
              "key": "documents",
              "label": "Documents",
              "tone": "primary"
            }
          },
          {
            "key": "images",
            "label": "Images",
            "value": 327,
            "maximum": 932,
            "displayValue": "327",
            "tone": "success",
            "status": {
              "key": "images",
              "label": "Images",
              "tone": "success"
            }
          },
          {
            "key": "other",
            "label": "Other",
            "value": 74,
            "maximum": 932,
            "displayValue": "74",
            "tone": "neutral",
            "status": {
              "key": "other",
              "label": "Other",
              "tone": "neutral"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "files-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "File activity",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Uploaded",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Downloaded",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "files-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Authorized files",
        "columns": [
          {
            "key": "file",
            "label": "File",
            "type": "text",
            "align": "left"
          },
          {
            "key": "type",
            "label": "Type",
            "type": "text",
            "align": "left"
          },
          {
            "key": "size",
            "label": "Size (KB)",
            "type": "number",
            "align": "right"
          },
          {
            "key": "scan",
            "label": "Scan",
            "type": "status",
            "align": "left"
          },
          {
            "key": "updated",
            "label": "Updated",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "files-row-1",
            "recordId": "files-record-1",
            "cells": {
              "file": "north-wing-closeout.pdf",
              "type": "PDF",
              "size": 2458,
              "scan": {
                "key": "clean",
                "label": "Available",
                "tone": "success"
              },
              "updated": "2026-09-04T14:08:00Z"
            }
          },
          {
            "id": "files-row-2",
            "recordId": "files-record-2",
            "cells": {
              "file": "north-wing-closeout.pdf - Follow-up",
              "type": "PDF",
              "size": 2459,
              "scan": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "updated": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "files-row-3",
            "recordId": "files-record-3",
            "cells": {
              "file": "north-wing-closeout.pdf - West region",
              "type": "PDF",
              "size": 2460,
              "scan": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "updated": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "files-row-4",
            "recordId": "files-record-4",
            "cells": {
              "file": "north-wing-closeout.pdf - Customer response",
              "type": "PDF",
              "size": 2461,
              "scan": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "updated": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "files-row-5",
            "recordId": "files-record-5",
            "cells": {
              "file": "north-wing-closeout.pdf - Regional operations review with a deliberately long title",
              "type": "PDF - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "size": 2462,
              "scan": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "updated": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "files-row-6",
            "recordId": "files-record-6",
            "cells": {
              "file": "north-wing-closeout.pdf - Completed preview",
              "type": "PDF",
              "size": 2463,
              "scan": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "updated": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 932,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "files-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "File activity",
        "hasMore": true,
        "items": [
          {
            "id": "files-event-1",
            "recordId": "files-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "File scan completed",
            "description": "The uploaded PDF passed content scanning.",
            "actor": "File security worker",
            "tone": "success"
          },
          {
            "id": "files-event-2",
            "recordId": "files-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "File scan completed - Follow-up",
            "description": "The uploaded PDF passed content scanning. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "files-event-3",
            "recordId": "files-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "File scan completed - West region",
            "description": "The uploaded PDF passed content scanning. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "files-event-4",
            "recordId": "files-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "File scan completed - Customer response",
            "description": "The uploaded PDF passed content scanning. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "files-event-5",
            "recordId": "files-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "File scan completed - Regional operations review with a deliberately long title",
            "description": "The uploaded PDF passed content scanning. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "files-event-6",
            "recordId": "files-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "File scan completed - Completed preview",
            "description": "The uploaded PDF passed content scanning. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface FilesPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface FilesPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: FilesPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function FilesPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: FilesPresentationProps) {
  if (error) return <p role="alert">The Files presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Files presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Files</p>
        <h1>File operations</h1>
        <p>Visible documents, scan state, attachment coverage, file types, and controlled activity.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/files`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "files-live",
      "_type": "module.files",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Model the business record first, then attach the file to it. Do not use folder names as a substitute for tenant, record, or location authorization.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/files.html).

---
title: "Conversations"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/conversations.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Conversations

Provides native channel threads with participants, messages, status, priority, internal notes, outbound replies, related context, activity, dynamic fields, and favorites.

## In brief

- **Runtime key:** module.conversations
- **Experience:** Customer & team communication
- **Security:** Server-enforced

Use Conversations for durable communication history across internal, email, SMS, form-driven, and other supported channels while Universal Inbox points people to the threads that need attention.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.conversations. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Provides native channel threads with participants, messages, status, priority, internal notes, outbound replies, related context, activity, dynamic fields, and favorites.

## Key capabilities

- Search and filter conversation threads by status.
- Create internal conversations and manage subject, priority, and lifecycle.
- Read escaped message history and post internal notes or permitted outbound replies.
- Expose unread/favorite state, dynamic fields, related records, and activity.

## Common uses

- Customer support and success communication.
- Project, sales, case, and operations correspondence.
- The native thread behind Universal Inbox triage and governed AI suggestions.

## How it connects

Inbound providers normalize into native Conversations and messages, then create or update Inbox attention. Threads can relate to Contacts, orders, projects, Work Orders, Files, and any authorized record without making Inbox the source of truth.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Conversation, message, channel, DataRole, and location access is enforced server-side. Outbound capability and edit rights are explicit; provider credentials and direct channel endpoints never reach the browser.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.conversations` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

### Explicit scope for create helpers

The native create helpers below require the user's current choice of Personal or one eligible DataRole. In a tenant-runtime component, render `RecordCreateScopeSelect allowAll` from `./RecordCreateScopeSelect` and read its submitted form with `readRecordCreateScope`. Pass that choice to the helper; do not infer it from the page, menu, role count, or a default location. When active locations exist, explicitly choose an authorized location or All when permitted; Personal has no location. For a shared-only helper, validate the returned choice is shared and has a DataRole before calling it. The typed choice is a request, and SQL rechecks current authority. Child actions keep their reviewed parent scope. Ordinary edits preserve the loaded scope and revision; moving scope is a separate explicit action.

## Copy/paste the Conversations page

The native block provides a secured thread queue, search/status filters, internal-thread creation, detail, edit/snooze state, messages, internal notes, outbound replies when permitted, attachments metadata, custom fields, and favorites:

```
{
  "blocks": [
    { "_id": "customer-conversations", "_type": "module.conversations", "props": {}, "children": [] }
  ]
}
```

### Custom unstyled queue and thread

The server applies status, channel, location, assignee, awaiting-reply, and search filters before returning a page. Message history is separately bounded to 1–500 messages; pass the oldest loaded timestamp as `beforeUtc` to request an older slice.

```
import { FormEvent, useEffect, useState } from "react";
import type { ConversationDetail, ConversationList, ConversationStatus } from "@buildwithhq/module-sdk";
import { getConversation, listConversations } from "./api";

const empty: ConversationList = { contractVersion: 1, pageNumber: 1, pageSize: 100, totalRecords: 0, totalPages: 0, totalIsExact: true, hasMore: false, items: [] };

export function UnstyledConversationQueue({ locationId = "", assignedToUserId = "" }) {
  const [draft, setDraft] = useState("");
  const [search, setSearch] = useState("");
  const [status, setStatus] = useState<ConversationStatus | "">("");
  const [awaitingReplyOnly, setAwaitingReplyOnly] = useState(false);
  const [page, setPage] = useState(1);
  const [result, setResult] = useState<ConversationList>(empty);
  const [selected, setSelected] = useState<ConversationDetail | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const controller = new AbortController();
    listConversations(search, status, controller.signal, undefined, locationId, assignedToUserId, awaitingReplyOnly, page, 100)
      .then(setResult)
      .catch((caught: unknown) => { if (!controller.signal.aborted) setError(caught instanceof Error ? caught.message : "Conversations could not be loaded."); });
    return () => controller.abort();
  }, [assignedToUserId, awaitingReplyOnly, locationId, page, search, status]);

  function submit(event: FormEvent) { event.preventDefault(); setPage(1); setSearch(draft.trim()); }
  async function open(recordId: string) { setSelected(await getConversation(recordId)); }
  async function loadOlder(current: ConversationDetail) {
    const oldest = current.messages[0]?.createdUtc;
    if (oldest) setSelected(await getConversation(current.recordId, undefined, 200, oldest));
  }

  return <section className="custom-conversations">
    <h1>Conversations</h1>
    <form role="search" onSubmit={submit}><label>Search<input value={draft} onChange={e => setDraft(e.target.value)} /></label><label>Status<select value={status} onChange={e => { setPage(1); setStatus(e.target.value as ConversationStatus | ""); }}><option value="">All</option><option>Open</option><option>Pending</option><option>Snoozed</option><option>Closed</option></select></label><label><input type="checkbox" checked={awaitingReplyOnly} onChange={e => { setPage(1); setAwaitingReplyOnly(e.target.checked); }} /> Awaiting reply</label><button>Search</button></form>
    {error && <p role="alert">{error}</p>}
    <ul>{result.items.map(thread => <li key={thread.recordId}><button onClick={() => void open(thread.recordId)}><strong>{thread.subject}</strong><span>{thread.channelName} - {thread.status} - Priority {thread.priority}</span><small>{thread.lastMessagePreview || "No messages"}</small></button></li>)}</ul>
    <nav><button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button><span>Page {result.pageNumber}</span><button disabled={!result.hasMore && page >= result.totalPages} onClick={() => setPage(value => value + 1)}>Next</button></nav>
    {selected && <article><h2>{selected.subject}</h2><p>{selected.channelName} - {selected.status}</p>{selected.messages.map(message => <section key={message.conversationMessageId}><strong>{message.isPrivateNote ? "Internal note" : message.direction}</strong><p>{message.bodyText || "HTML message"}</p><small>{message.deliveryStatus}</small></section>)}{selected.messages.length === 200 && <button onClick={() => void loadOlder(selected)}>Load older messages</button>}</article>}
  </section>;
}
```

### Create, replace, reply, and send directly

Conversation replacement requires a fresh `updatedUtc`. Only offer Outbound when detail returns `isOutboundCapable=true`; otherwise post a private Note. Provider delivery is asynchronous and its returned delivery state is authoritative. Direct tenant-user messages use a client message ID for idempotency.

```
import type { ConversationDetail, ConversationDynamicField } from "@buildwithhq/module-sdk";
import { createConversation, getConversation, postConversationMessage, sendDirectConversation, setConversationFavorite, updateConversation } from "./api";
import type { RecordCreateScope } from "./RecordCreateScopeSelect";

const fieldInput = (field: ConversationDynamicField) => ({ fieldKey: field.fieldKey, valueText: field.valueText ?? undefined, valueInt: field.valueInt ?? undefined, valueDecimal: field.valueDecimal ?? undefined, valueDateTime: field.valueDateTime ?? undefined, valueBool: field.valueBool ?? undefined, valueGuid: field.valueGuid ?? undefined, valueJson: field.valueJson });

export function createInternalThread(subject: string, chosenScope: RecordCreateScope, contactRecordId?: string) {
  return createConversation({ ...chosenScope, subject, contactRecordId, priority: 2 });
}

export async function closeThread(current: ConversationDetail) {
  await updateConversation(current.recordId, {
    expectedUpdatedUtc: current.updatedUtc, subject: current.subject, status: "Closed", priority: current.priority,
    assignedToUserId: current.assignedToUserId || undefined, locationId: current.locationId || undefined,
    contactRecordId: current.contactRecordId || undefined, dynamicFields: current.dynamicFields.map(fieldInput),
  });
  return getConversation(current.recordId);
}

export async function addInternalNote(current: ConversationDetail, text: string) {
  await postConversationMessage(current.recordId, { direction: "Note", bodyText: text });
  return getConversation(current.recordId);
}

export async function replyToCustomer(current: ConversationDetail, text: string) {
  if (!current.isOutboundCapable) throw new Error("This channel does not permit outbound replies.");
  await postConversationMessage(current.recordId, { direction: "Outbound", bodyText: text });
  return getConversation(current.recordId);
}

export function messageTenantUser(recipientUserId: string, bodyText: string) {
  return sendDirectConversation({ recipientUserId, clientMessageId: crypto.randomUUID(), bodyText });
}

export async function toggleConversationFavorite(current: ConversationDetail) {
  await setConversationFavorite(current.recordId, !current.isFavorite);
  return getConversation(current.recordId);
}
```

### Optional starter styling

```
.custom-conversations { width: 100%; max-width: none; }
.custom-conversations form, .custom-conversations nav { align-items: end; display: flex; gap: .75rem; }
.custom-conversations > ul { list-style: none; margin: 1rem 0; padding: 0; }
.custom-conversations > ul button { background: transparent; border: 0; display: grid; gap: .2rem; padding: .75rem 0; text-align: left; width: 100%; }
.custom-conversations article { border: 1px solid var(--line, #d8dee8); margin-top: 1rem; padding: 1rem; }
.custom-conversations article section { border-top: 1px solid var(--line, #d8dee8); padding: .75rem 0; }
```

### Exact data path

| Purpose | Route | Procedure |
| --- | --- | --- |
| Queue/detail | `GET /api/modules/conversations`, `GET /api/modules/conversations/{recordId}` | `sp_Conversations_ListSecured`, `sp_Conversations_GetSecured` |
| Create/replace | `POST /api/modules/conversations`, `PUT /api/modules/conversations/{recordId}` | `sp_Conversations_CreateSecured`, `sp_Conversations_UpdateSecured` |
| Note/outbound reply | `POST /api/modules/conversations/{recordId}/messages` | `sp_Conversations_ReplySecured` |
| Direct tenant message | `POST /api/modules/conversations/direct` | `sp_Conversations_SendDirectSecured` |
| Favorite | `PUT /api/modules/conversations/{recordId}/favorite` | `sp_Conversations_SetFavoriteSecured` |

Universal Inbox is the attention layer; Conversation remains the message source of truth. Never duplicate messages into page state or treat an Inbox item as the thread. Outbound capability, channel connection, contact, assignee, location, and every attachment are reauthorized server-side.

## Build a professional Conversations dashboard

These six registry-backed presentation blocks let a designer turn the secured Conversations API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/conversations`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/conversations-sample.json`, its executable authenticated page at `pages/first-class/conversations-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Conversations projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Open, unread, waiting, and message-volume counts |
| `entity-list` | `core.entity-list` | Recent permitted threads with channel and participant |
| `progress-list` | `core.progress-list` | Distribution by channel, state, queue, or owner |
| `series-chart` | `core.series-chart` | Inbound and outbound messages over time |
| `data-grid` | `core.presentation-grid` | One bounded thread page without hidden message content |
| `timeline` | `core.timeline` | Thread creation, messages, assignment, reply, reopen, and resolution |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "conversations-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Conversation center",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "open",
            "label": "Open threads",
            "value": 73,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "unread",
            "label": "Unread",
            "value": 19,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "waiting",
            "label": "Waiting for us",
            "value": 11,
            "format": "number",
            "tone": "danger"
          },
          {
            "key": "today",
            "label": "Messages today",
            "value": 146,
            "format": "number",
            "tone": "success"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "conversations-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Recent conversations",
        "hasMore": true,
        "items": [
          {
            "id": "conversations-sample-1",
            "recordId": "conversations-record-1",
            "primary": "Installation timing",
            "secondary": "Maya Chen - Email",
            "status": {
              "key": "waiting-for-us",
              "label": "Waiting for us",
              "tone": "warning"
            },
            "trailing": "4 messages"
          },
          {
            "id": "conversations-sample-2",
            "recordId": "conversations-record-2",
            "primary": "Installation timing - Follow-up",
            "secondary": "Maya Chen - Email - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "conversations-sample-3",
            "recordId": "conversations-record-3",
            "primary": "Installation timing - West region",
            "secondary": "Maya Chen - Email - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "conversations-sample-4",
            "recordId": "conversations-record-4",
            "primary": "Installation timing - Customer response",
            "secondary": "Maya Chen - Email - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "conversations-sample-5",
            "recordId": "conversations-record-5",
            "primary": "Installation timing - Regional operations review with a deliberately long title",
            "secondary": "Maya Chen - Email - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "conversations-sample-6",
            "recordId": "conversations-record-6",
            "primary": "Installation timing - Completed preview",
            "secondary": "Maya Chen - Email - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "conversations-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Threads by channel",
        "items": [
          {
            "key": "email",
            "label": "Email",
            "value": 45,
            "maximum": 73,
            "displayValue": "45",
            "tone": "primary",
            "status": {
              "key": "email",
              "label": "Email",
              "tone": "primary"
            }
          },
          {
            "key": "sms",
            "label": "SMS",
            "value": 18,
            "maximum": 73,
            "displayValue": "18",
            "tone": "success",
            "status": {
              "key": "sms",
              "label": "SMS",
              "tone": "success"
            }
          },
          {
            "key": "internal",
            "label": "Internal",
            "value": 10,
            "maximum": 73,
            "displayValue": "10",
            "tone": "neutral",
            "status": {
              "key": "internal",
              "label": "Internal",
              "tone": "neutral"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "conversations-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Message volume",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Inbound",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Outbound",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "conversations-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Visible conversations",
        "columns": [
          {
            "key": "subject",
            "label": "Subject",
            "type": "text",
            "align": "left"
          },
          {
            "key": "channel",
            "label": "Channel",
            "type": "text",
            "align": "left"
          },
          {
            "key": "participant",
            "label": "Participant",
            "type": "text",
            "align": "left"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "updated",
            "label": "Updated",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "conversations-row-1",
            "recordId": "conversations-record-1",
            "cells": {
              "subject": "Installation timing",
              "channel": "Email",
              "participant": "Maya Chen",
              "status": {
                "key": "waiting",
                "label": "Waiting for us",
                "tone": "warning"
              },
              "updated": "2026-09-04T17:28:00Z"
            }
          },
          {
            "id": "conversations-row-2",
            "recordId": "conversations-record-2",
            "cells": {
              "subject": "Installation timing - Follow-up",
              "channel": "Email",
              "participant": "Maya Chen",
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "updated": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "conversations-row-3",
            "recordId": "conversations-record-3",
            "cells": {
              "subject": "Installation timing - West region",
              "channel": "Email",
              "participant": "Maya Chen",
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "updated": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "conversations-row-4",
            "recordId": "conversations-record-4",
            "cells": {
              "subject": "Installation timing - Customer response",
              "channel": "Email",
              "participant": "Maya Chen",
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "updated": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "conversations-row-5",
            "recordId": "conversations-record-5",
            "cells": {
              "subject": "Installation timing - Regional operations review with a deliberately long title",
              "channel": "Email - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "participant": "Maya Chen",
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "updated": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "conversations-row-6",
            "recordId": "conversations-record-6",
            "cells": {
              "subject": "Installation timing - Completed preview",
              "channel": "Email",
              "participant": "Maya Chen",
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "updated": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 73,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "conversations-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Conversation activity",
        "hasMore": true,
        "items": [
          {
            "id": "conversations-event-1",
            "recordId": "conversations-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Inbound reply received",
            "description": "The customer replied to Installation timing.",
            "actor": "Maya Chen",
            "tone": "primary"
          },
          {
            "id": "conversations-event-2",
            "recordId": "conversations-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Inbound reply received - Follow-up",
            "description": "The customer replied to Installation timing. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "conversations-event-3",
            "recordId": "conversations-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Inbound reply received - West region",
            "description": "The customer replied to Installation timing. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "conversations-event-4",
            "recordId": "conversations-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Inbound reply received - Customer response",
            "description": "The customer replied to Installation timing. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "conversations-event-5",
            "recordId": "conversations-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Inbound reply received - Regional operations review with a deliberately long title",
            "description": "The customer replied to Installation timing. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "conversations-event-6",
            "recordId": "conversations-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Inbound reply received - Completed preview",
            "description": "The customer replied to Installation timing. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface ConversationsPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface ConversationsPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: ConversationsPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function ConversationsPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: ConversationsPresentationProps) {
  if (error) return <p role="alert">The Conversations presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Conversations presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Conversations</p>
        <h1>Conversation center</h1>
        <p>Open threads, unread activity, channels, response state, and recent messages.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/conversations`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "conversations-live",
      "_type": "module.conversations",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Use one canonical thread per real conversation and relate it to business context. Avoid copying message bodies into custom records or building a second inbox table family.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/conversations.html).

---
title: "Company news"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/company-news.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Company news

Publishes searchable internal announcements with draft, scheduled, published, and expired visibility, author controls, custom fields, relationships, activity, and favorites.

## In brief

- **Runtime key:** module.company-news
- **Experience:** Announcements
- **Security:** Server-enforced

Use Company News for controlled organization-wide or location-scoped announcements such as policy changes, releases, leadership updates, closures, and internal notices.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.company-news. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Publishes searchable internal announcements with draft, scheduled, published, and expired visibility, author controls, custom fields, relationships, activity, and favorites.

## Key capabilities

- Search visible announcements and open their secured detail.
- Author and edit announcements only when the response grants edit permission.
- Control draft, scheduled, published, and expired visibility.
- Connect announcements to records, activity, custom fields, and personal favorites.

## Common uses

- Internal news and release announcements.
- Location-specific closures, safety notices, or operating updates.
- Policy and program communications linked to supporting records or files.

## How it connects

Announcements can link to Knowledge Articles, Files, Web Links, and other records for durable supporting detail. Notifications can call attention to a published announcement without replacing the announcement itself.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Publication state, SaaS, tenant, DataRole, and location are evaluated by secured reads. Announcement bodies render as escaped text, and authoring controls depend on server-reported permission.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.company-news` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

### Explicit scope for create helpers

The native create helpers below require the user's current choice of one eligible DataRole with `isPersonal: false`. In a tenant-runtime component, render `RecordCreateScopeSelect allowAll allowPersonal={false}` from `./RecordCreateScopeSelect` and read its submitted form with `readRecordCreateScope`. Pass that choice to the helper; do not infer it from the page, menu, role count, or a default location. When active locations exist, explicitly choose an authorized location or All when permitted; Personal has no location. For a shared-only helper, validate the returned choice is shared and has a DataRole before calling it. The typed choice is a request, and SQL rechecks current authority. Child actions keep their reviewed parent scope. Ordinary edits preserve the loaded scope and revision; moving scope is a separate explicit action.

## Copy/paste the Company News page

The native block supplies secured published/draft visibility, search, create/edit controls driven by `canEdit`, detail, custom fields, relation/activity counts, and favorites:

```
{
  "blocks": [
    { "_id": "company-announcements", "_type": "module.company-news", "props": {}, "children": [] }
  ]
}
```

### Custom unstyled news page

Set `includeDrafts` only for an authoring view. The server still decides whether the current user may see or edit drafts. Search, location, publication rules, and paging are applied before rows reach React.

```
import { FormEvent, useEffect, useState } from "react";
import type { CompanyNewsDetail, CompanyNewsList } from "@buildwithhq/module-sdk";
import { getCompanyNews, listCompanyNews } from "./api";

const empty: CompanyNewsList = { contractVersion: 1, pageNumber: 1, pageSize: 50, totalRecords: 0, totalPages: 0, totalIsExact: false, hasMore: false, canCreate: false, canEdit: false, items: [] };

export function UnstyledCompanyNews({ authoring = false, locationId = "" }) {
  const [draft, setDraft] = useState("");
  const [search, setSearch] = useState("");
  const [page, setPage] = useState(1);
  const [result, setResult] = useState<CompanyNewsList>(empty);
  const [selected, setSelected] = useState<CompanyNewsDetail | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const controller = new AbortController();
    listCompanyNews(search, authoring, controller.signal, locationId, page, 50)
      .then(setResult)
      .catch((caught: unknown) => { if (!controller.signal.aborted) setError(caught instanceof Error ? caught.message : "News could not be loaded."); });
    return () => controller.abort();
  }, [authoring, locationId, page, search]);

  function submit(event: FormEvent) { event.preventDefault(); setPage(1); setSearch(draft.trim()); }
  async function open(recordId: string) { setSelected(await getCompanyNews(recordId)); }

  return <section className="custom-news">
    <header><h1>Company news</h1>{result.canEdit && <a href="#news-composer">New announcement</a>}</header>
    <form role="search" onSubmit={submit}><label>Search<input value={draft} onChange={e => setDraft(e.target.value)} /></label><button>Search</button></form>
    {error && <p role="alert">{error}</p>}
    <ol>{result.items.map(item => <li key={item.recordId}><button onClick={() => void open(item.recordId)}><strong>{item.title}</strong><span>{item.isPublished ? "Published" : "Draft"} - {item.locationName || "All locations"}</span></button></li>)}</ol>
    <nav><button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button><span>Page {result.pageNumber} of {Math.max(1, result.totalPages)}</span><button disabled={page >= result.totalPages} onClick={() => setPage(value => value + 1)}>Next</button></nav>
    {selected && <article><h2>{selected.title}</h2><p>{selected.body}</p><small>{selected.status} - {selected.createdByDisplayName || "Company news"}</small></article>}
  </section>;
}
```

### Create, schedule, replace, and favorite

An update is an optimistic full replacement. Preserve publication times, location, dynamic fields, and the latest `updatedUtc`. A future `publishUtc` schedules visibility; `expiresUtc` removes it from ordinary published reads after expiry.

```
import type { CompanyNewsDetail, CompanyNewsDynamicField } from "@buildwithhq/module-sdk";
import { createCompanyNews, getCompanyNews, setCompanyNewsFavorite, updateCompanyNews } from "./api";
import type { RecordCreateScope } from "./RecordCreateScopeSelect";
type SharedScope = RecordCreateScope & { isPersonal: false; dataRoleId: number };

const fieldInput = (field: CompanyNewsDynamicField) => ({ fieldKey: field.fieldKey, valueText: field.valueText ?? undefined, valueInt: field.valueInt ?? undefined, valueDecimal: field.valueDecimal ?? undefined, valueDateTime: field.valueDateTime ?? undefined, valueBool: field.valueBool ?? undefined, valueGuid: field.valueGuid ?? undefined, valueJson: field.valueJson });

export function createDraftAnnouncement(title: string, body: string, chosenScope: SharedScope) {
  return createCompanyNews({ ...chosenScope, title, body, isPublished: false, dynamicFields: [] });
}

export async function publishAnnouncement(current: CompanyNewsDetail, publishUtc = new Date().toISOString()) {
  if (!current.canEdit) throw new Error("The signed-in user cannot edit this announcement.");
  await updateCompanyNews(current.recordId, {
    expectedUpdatedUtc: current.updatedUtc, title: current.title, body: current.body || "",
    locationId: current.locationId || undefined, publishUtc, expiresUtc: current.expiresUtc || undefined,
    isPublished: true, dynamicFields: current.dynamicFields.map(fieldInput),
  });
  return getCompanyNews(current.recordId);
}

export async function toggleNewsFavorite(current: CompanyNewsDetail) {
  await setCompanyNewsFavorite(current.recordId, !current.isFavorite);
  return getCompanyNews(current.recordId);
}
```

### Optional starter styling

```
.custom-news { width: 100%; max-width: none; }
.custom-news > header, .custom-news form, .custom-news nav { align-items: center; display: flex; gap: .75rem; justify-content: space-between; }
.custom-news ol { list-style: none; margin: 1rem 0; padding: 0; }
.custom-news li button { background: transparent; border: 0; display: grid; gap: .2rem; padding: .75rem 0; text-align: left; width: 100%; }
.custom-news article { border: 1px solid var(--line, #d8dee8); margin-top: 1rem; padding: 1rem; white-space: pre-wrap; }
```

### Exact data path

| Purpose | Route | Procedure |
| --- | --- | --- |
| List/detail | `GET /api/modules/company-news`, `GET /api/modules/company-news/{recordId}` | `sp_CompanyNews_ListSecured`, `sp_CompanyNews_GetSecured` |
| Create/replace | `POST /api/modules/company-news`, `PUT /api/modules/company-news/{recordId}` | `sp_CompanyNews_CreateSecured`, `sp_CompanyNews_UpdateSecured` |
| Favorite | `PUT /api/modules/company-news/{recordId}/favorite` | `sp_CompanyNews_SetFavoriteSecured` |

Title is limited to 300 characters, list page size to 200, and dynamic inputs to 200 unique field keys. The API returns escaped text; a custom renderer must not inject an announcement body with `dangerouslySetInnerHTML`.

## Build a professional Company news dashboard

These six registry-backed presentation blocks let a designer turn the secured Company news API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/company-news`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/company-news-sample.json`, its executable authenticated page at `pages/first-class/company-news-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Company news projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Published, draft, scheduled, and expiring counts |
| `entity-list` | `core.entity-list` | Recent announcements within the user's audience |
| `progress-list` | `core.progress-list` | Distribution by lifecycle, audience, or category |
| `series-chart` | `core.series-chart` | Publishing and archival activity |
| `data-grid` | `core.presentation-grid` | One bounded editorial page with safe text |
| `timeline` | `core.timeline` | Draft, schedule, publish, edit, expire, and archive events |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "company-news-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Company news overview",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "published",
            "label": "Published",
            "value": 42,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "drafts",
            "label": "Drafts",
            "value": 6,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "scheduled",
            "label": "Scheduled",
            "value": 3,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "expiring",
            "label": "Expiring soon",
            "value": 2,
            "format": "number",
            "tone": "warning"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "company-news-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Recent announcements",
        "hasMore": true,
        "items": [
          {
            "id": "company-news-sample-1",
            "recordId": "company-news-record-1",
            "primary": "New field safety standard",
            "secondary": "Operations - all locations",
            "status": {
              "key": "published",
              "label": "Published",
              "tone": "success"
            },
            "trailing": "Sep 4"
          },
          {
            "id": "company-news-sample-2",
            "recordId": "company-news-record-2",
            "primary": "New field safety standard - Follow-up",
            "secondary": "Operations - all locations - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "company-news-sample-3",
            "recordId": "company-news-record-3",
            "primary": "New field safety standard - West region",
            "secondary": "Operations - all locations - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "company-news-sample-4",
            "recordId": "company-news-record-4",
            "primary": "New field safety standard - Customer response",
            "secondary": "Operations - all locations - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "company-news-sample-5",
            "recordId": "company-news-record-5",
            "primary": "New field safety standard - Regional operations review with a deliberately long title",
            "secondary": "Operations - all locations - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "company-news-sample-6",
            "recordId": "company-news-record-6",
            "primary": "New field safety standard - Completed preview",
            "secondary": "Operations - all locations - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "company-news-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Announcements by state",
        "items": [
          {
            "key": "published",
            "label": "Published",
            "value": 42,
            "maximum": 51,
            "displayValue": "42",
            "tone": "success",
            "status": {
              "key": "published",
              "label": "Published",
              "tone": "success"
            }
          },
          {
            "key": "draft",
            "label": "Draft",
            "value": 6,
            "maximum": 51,
            "displayValue": "6",
            "tone": "neutral",
            "status": {
              "key": "draft",
              "label": "Draft",
              "tone": "neutral"
            }
          },
          {
            "key": "scheduled",
            "label": "Scheduled",
            "value": 3,
            "maximum": 51,
            "displayValue": "3",
            "tone": "primary",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "primary"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "company-news-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Publishing activity",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Published",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Archived",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "company-news-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Announcements",
        "columns": [
          {
            "key": "title",
            "label": "Announcement",
            "type": "text",
            "align": "left"
          },
          {
            "key": "audience",
            "label": "Audience",
            "type": "text",
            "align": "left"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "publish",
            "label": "Publish time",
            "type": "date",
            "align": "left"
          },
          {
            "key": "author",
            "label": "Author",
            "type": "text",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "company-news-row-1",
            "recordId": "company-news-record-1",
            "cells": {
              "title": "New field safety standard",
              "audience": "All locations",
              "status": {
                "key": "published",
                "label": "Published",
                "tone": "success"
              },
              "publish": "2026-09-04T16:00:00Z",
              "author": "Operations"
            }
          },
          {
            "id": "company-news-row-2",
            "recordId": "company-news-record-2",
            "cells": {
              "title": "New field safety standard - Follow-up",
              "audience": "All locations",
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "publish": "2026-09-04T15:42:00Z",
              "author": "Operations"
            }
          },
          {
            "id": "company-news-row-3",
            "recordId": "company-news-record-3",
            "cells": {
              "title": "New field safety standard - West region",
              "audience": "All locations",
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "publish": "2026-09-04T12:18:00Z",
              "author": "Operations"
            }
          },
          {
            "id": "company-news-row-4",
            "recordId": "company-news-record-4",
            "cells": {
              "title": "New field safety standard - Customer response",
              "audience": "All locations",
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "publish": "2026-09-03T21:07:00Z",
              "author": "Operations"
            }
          },
          {
            "id": "company-news-row-5",
            "recordId": "company-news-record-5",
            "cells": {
              "title": "New field safety standard - Regional operations review with a deliberately long title",
              "audience": "All locations - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "publish": "2026-09-03T16:31:00Z",
              "author": "Operations"
            }
          },
          {
            "id": "company-news-row-6",
            "recordId": "company-news-record-6",
            "cells": {
              "title": "New field safety standard - Completed preview",
              "audience": "All locations",
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "publish": "2026-09-02T19:14:00Z",
              "author": "Operations"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 42,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "company-news-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Editorial timeline",
        "hasMore": true,
        "items": [
          {
            "id": "company-news-event-1",
            "recordId": "company-news-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Announcement published",
            "description": "New field safety standard became visible to its audience.",
            "actor": "Operations",
            "tone": "success"
          },
          {
            "id": "company-news-event-2",
            "recordId": "company-news-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Announcement published - Follow-up",
            "description": "New field safety standard became visible to its audience. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "company-news-event-3",
            "recordId": "company-news-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Announcement published - West region",
            "description": "New field safety standard became visible to its audience. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "company-news-event-4",
            "recordId": "company-news-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Announcement published - Customer response",
            "description": "New field safety standard became visible to its audience. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "company-news-event-5",
            "recordId": "company-news-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Announcement published - Regional operations review with a deliberately long title",
            "description": "New field safety standard became visible to its audience. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "company-news-event-6",
            "recordId": "company-news-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Announcement published - Completed preview",
            "description": "New field safety standard became visible to its audience. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface CompanyNewsPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface CompanyNewsPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: CompanyNewsPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function CompanyNewsPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: CompanyNewsPresentationProps) {
  if (error) return <p role="alert">The Company news presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Company news presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Company news</p>
        <h1>Company news overview</h1>
        <p>Published announcements, drafts, schedules, audience reach, and editorial activity.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/company-news`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "company-news-live",
      "_type": "module.company-news",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Use Company News for timely announcements and Knowledge Articles for maintained reference material. Link the two when an announcement introduces a lasting policy.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/company-news.html).

---
title: "Knowledge Core"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/knowledge-core.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Knowledge Core

Turns tenant knowledge into owned, revisioned, reviewable records that connect to business context, answer questions, support permission-aware AI/RAG, and learn safely from resolved support work.

## In brief

- **Runtime key:** module.knowledge-articles
- **Experience:** Maintained, cited knowledge
- **Security:** Server-enforced

Use Knowledge Core for policies, procedures, product help, FAQs, playbooks, support resolutions, and other maintained reference material whose ownership, revision, freshness, audience, and AI use must remain explicit.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.knowledge-articles. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Turns tenant knowledge into owned, revisioned, reviewable records that connect to business context, answer questions, support permission-aware AI/RAG, and learn safely from resolved support work.

## Key capabilities

- Create Draft knowledge and publish or archive it through permission-checked lifecycle actions.
- Preserve immutable revisions, publication history, authority, AI eligibility, and optimistic-concurrency evidence.
- Assign one primary accountable owner to a user or DataRole and schedule recurring review work.
- Relate knowledge to any authorized `RecordId` and retrieve bounded contextual knowledge without copying the business record.
- Capture unanswered questions, repeated occurrences, usage, feedback, and secured knowledge-gap signals.
- Register only Published, AI-eligible revisions for secured semantic/multimodal retrieval with exact citations.
- Bring current support knowledge into fenced GoClaw Inbox context and turn resolved cases into sanitized Draft candidates.

## Ownership, revisions, and lifecycle

Each item remains one canonical Record and Knowledge Core item. Its lifecycle is **Draft**, **Published**, or **Archived**; publication and archive are explicit permission-checked actions. Editing creates an immutable revision instead of erasing the evidence behind an earlier answer or citation. Stale browser updates are rejected through the item's expected update timestamp.

An active primary owner is either a named user or a DataRole, never an ambiguous mixture. Ownership makes review and escalation accountable without granting the owner access beyond normal tenant, DataRole, record, field, and location rules.

## Reviews and freshness

A review policy sets the interval, due-soon window, stale threshold, and whether a review Task is created. Due work appears through the existing Tasks and Universal Inbox attention surfaces. An authorized reviewer can confirm the current revision, revise and republish it, reassign the review, or archive the item. Confirming current schedules the next review without pretending the content changed.

Freshness is evidence, not decoration. Current, due-soon, due, and stale states help users and AI distinguish maintained guidance from material that needs review. Stale content does not silently become authoritative merely because it still matches a search.

## Relations and contextual knowledge

Knowledge can be linked to a customer, product, case, work order, conversation, file, or any other authorized `RecordId`. Related and contextual reads traverse the existing secured record graph within bounded depth and result limits. A relation improves context; it never grants access to either endpoint.

## Questions, feedback, and knowledge gaps

When a user or GoClaw cannot find authoritative evidence, Knowledge Core records a question instead of fabricating an answer. Repeated occurrences are grouped inside the same tenant and may be assigned, answered, closed, or converted into a normal **GeneratedCandidate** Draft for review.

Usage and feedback such as helpful, outdated, or incorrect remain linked to the visible item and context. The health view combines repeated questions, weak/no-evidence retrieval, negative feedback, stale high-use sources, overdue reviews, and missing owners into secured gap signals. Aggregate counts never reveal an inaccessible question or source.

## Secured AI, RAG, and citations

Only an explicitly Published and AI-eligible revision enters the canonical AI source, document-element, chunk, visual-index, and embedding pipeline. Tenant, `CanAiReadRecords`, DataRole, location, record, and field security are applied before model context is assembled and again when stored record identities are returned.

Answers retain the Knowledge item, immutable revision, authority, publication/review freshness, source, page, and visual evidence needed for a citation. Contextual record links can improve ranking, but relevance never grants access. Draft, archived, deleted, AI-excluded, or unauthorized material is absent from normal retrieval.

## Universal Inbox, GoClaw, and support learning

Universal Inbox remains the support attention layer. GoClaw must hold the current claim/lease and exact `ActivityVersion` before assembling secured support context. Customer-visible citations include only support-eligible sources the represented user may disclose; internal-only knowledge is omitted. Read-only diagnostics can describe current account state, while RAG explains how the system should work. Neither authorizes a mutation.

After a case is Resolved or Closed, the controlled learning path accepts structured symptom, product area, likely cause, diagnostic steps, verified resolution, and affected-version fields—not the raw transcript. The `support-resolution-v1` sanitizer removes credentials, secrets, PII, and tenant-specific identifiers. The result is an idempotent **SupportResolution** Draft with **GeneratedCandidate** authority, a source Inbox/version link, one owner, and a review Task. It remains unavailable to normal RAG until an authorized human reviews, marks it eligible, and publishes it.

## OpsAtlas — AI Operational Knowledge Core

Your company’s operating knowledge, mapped and available on demand.

OpsAtlas is the thirteenth Build This product pattern and a complete product experience built on Knowledge Core. It turns SOPs, policies, manuals, training, system documentation, and hard-won tribal knowledge into maintained operating memory for employees and permission-bound AI assistants.

[How to build OpsAtlas](../how-to-do-this/opsatlas.html) [Explore the OpsAtlas product concept](https://buildwithhq.com/buildthis/opsatlas.html)

### What OpsAtlas can do

- Ingest approved SOPs, policies, manuals, training material, system documentation, and tribal knowledge.
- Chunk, embed, version, and relate that knowledge while retaining source and revision evidence.
- Respect department, DataRole, location, record, field, and `CanAiReadRecords` permissions before retrieval or model context.
- Give employees evidence-backed answers to *How do we do this?* with exact sources, revisions, and freshness.
- Launch the appropriate BuildWithHQ workflow from an answer while preserving action permission, approval, and current-context checks.
- Give GoClaw agents and approved MCP tools the permitted operational context they need before they plan or act.
- Reduce repetitive internal questions and accelerate employee onboarding.
- Standardize procedures across teams and locations without flattening their access boundaries.
- Preserve institutional knowledge when employees, contractors, or specialists leave.
- Identify unanswered questions, weak answers, stale sources, negative feedback, and documentation gaps.

### The continuous knowledge flywheel

| Stage | What happens |
| --- | --- |
| **Capture** | Bring approved operating sources and reusable support knowledge into accountable collections. |
| **Understand** | Extract text and visual evidence, create revisions, relate business context, and build secured semantic indexes. |
| **Retrieve** | Return the strongest authorized current guidance with citations, freshness, and explicit gaps. |
| **Act + Improve** | Start governed workflows, collect usage and feedback, answer questions, and route Draft improvements to their owners. |

**Capture → Understand → Retrieve → Act + Improve** is continuous: each real question or support outcome can reveal what should be reviewed, clarified, or added next without automatically promoting private or generated material.

### OpsAtlas and CompanyIQ answer different questions

| Product pattern | Primary question | Focus |
| --- | --- | --- |
| **OpsAtlas** | How do we operate? | Current procedures, policy, training, operating guidance, evidence, and the governed workflow that follows. |
| **CompanyIQ** | What is happening in the business, and where is the opportunity? | Signals, company context, risks, opportunities, evidence-backed insights, and reviewable next actions. |

The two products can share BuildWithHQ’s secured records, relationships, AI retrieval, and action foundations. OpsAtlas organizes the business’s operating memory; CompanyIQ uses permitted business evidence to understand change and opportunity.

## Common uses

- Owned product documentation, policies, procedures, FAQs, and employee help.
- Customer-safe help centers and support answers with exact current citations.
- Contextual playbooks linked to customers, products, cases, work orders, files, and conversations.
- Permission-aware AI/RAG sources whose authority and freshness must be inspectable.
- A controlled support learning loop that turns reusable resolutions into reviewable Drafts.

## How it connects

Knowledge Core composes with Files and Web Links for source evidence, Record Relations for business context, Tasks and Universal Inbox for review/support attention, GoClaw for fenced assistance, and the existing AI ingestion/retrieval chain for cited answers. The Knowledge item and immutable revision remain the source of truth throughout.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Every list, item, relation, review, question, feedback, support-context, and AI path derives the SaaS app, tenant, user, DataRole, location, record, field, and permission scope from verified server identity. `CanAiReadRecords` is required before AI context. Publication, ownership, review, support learning, and archive actions have separate permission checks; customer-visible context excludes internal-only sources.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and add the validated `module.knowledge-articles` block to the pages and existing user-type menus that need Knowledge Core.
2. Create collections around reader/support journeys and assign their audience, default owner, review policy, and existing DataRole/location visibility.
3. Create or migrate source items as Drafts, confirm their authority and AI/support eligibility, then publish through the reviewed lifecycle.
4. Link knowledge to relevant Records, configure the review worker/Tasks and Inbox attention, and enable GoClaw support context only for permitted users and queues.
5. Test Draft/Published/Archived visibility, revision restore, stale updates, owner review, questions/feedback, cross-tenant/location denial, AI-read denial, internal-source exclusion, exact citations, stale Inbox activity, and Draft support learning before publishing an exact app version.

### Explicit scope for create helpers

The native create helpers below require the user's current choice of one eligible DataRole with `isPersonal: false`. In a tenant-runtime component, render `RecordCreateScopeSelect allowAll allowPersonal={false}` from `./RecordCreateScopeSelect` and read its submitted form with `readRecordCreateScope`. Pass that choice to the helper; do not infer it from the page, menu, role count, or a default location. When active locations exist, explicitly choose an authorized location or All when permitted; Personal has no location. For a shared-only helper, validate the returned choice is shared and has a DataRole before calling it. The typed choice is a request, and SQL rechecks current authority. Child actions keep their reviewed parent scope. Ordinary edits preserve the loaded scope and revision; moving scope is a separate explicit action.

## Copy/paste the native knowledge page

The native block is the compatibility reader/editor for searchable articles, drafts, detail, dynamic fields, relationships, activity, and favorites. Paste it for the fastest page. Use the custom Knowledge Core workspace below when you need explicit lifecycle, ownership, reviews, questions, and health:

```
{
  "blocks": [
    { "_id": "knowledge-library", "_type": "module.knowledge-articles", "props": {}, "children": [] }
  ]
}
```

### Custom unstyled Knowledge Core workspace

This uses the version 2 Knowledge Core contract. Search, lifecycle, type, location, and pagination are applied by `sp_kc_ListKnowledgeItemsSecured`; the component receives only its authorized page.

```
import { FormEvent, useEffect, useState } from "react";
import type { KnowledgeCoreDetail, KnowledgeCoreList, KnowledgeHealth, KnowledgeLifecycleStatus } from "@buildwithhq/module-sdk";
import { getKnowledgeCore, getKnowledgeHealth, listKnowledgeCore } from "./api";

const empty: KnowledgeCoreList = { contractVersion: 2, pageNumber: 1, pageSize: 50, totalRecords: 0, totalPages: 0, canCreate: false, canManage: false, items: [] };

export function KnowledgeCoreWorkspace({ locationId = "" }) {
  const [draftSearch, setDraftSearch] = useState("");
  const [search, setSearch] = useState("");
  const [lifecycle, setLifecycle] = useState<KnowledgeLifecycleStatus | "">("");
  const [knowledgeType, setKnowledgeType] = useState("");
  const [page, setPage] = useState(1);
  const [result, setResult] = useState<KnowledgeCoreList>(empty);
  const [health, setHealth] = useState<KnowledgeHealth | null>(null);
  const [selected, setSelected] = useState<KnowledgeCoreDetail | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const controller = new AbortController();
    Promise.all([
      listKnowledgeCore(search, lifecycle, knowledgeType, controller.signal, locationId, page, 50),
      getKnowledgeHealth(controller.signal),
    ]).then(([items, status]) => { setResult(items); setHealth(status); })
      .catch((caught: unknown) => { if (!controller.signal.aborted) setError(caught instanceof Error ? caught.message : "Knowledge could not be loaded."); });
    return () => controller.abort();
  }, [knowledgeType, lifecycle, locationId, page, search]);

  function submit(event: FormEvent) { event.preventDefault(); setPage(1); setSearch(draftSearch.trim()); }
  async function open(recordId: string) { setSelected(await getKnowledgeCore(recordId)); }

  return <section className="knowledge-core">
    <h1>Knowledge Core</h1>
    {health && <p>{health.publishedCount} published - {health.reviewDueCount} reviews due - {health.openQuestionCount} open questions - {health.staleCount} stale</p>}
    <form role="search" onSubmit={submit}><label>Search<input value={draftSearch} onChange={e => setDraftSearch(e.target.value)} /></label><label>Lifecycle<select value={lifecycle} onChange={e => { setPage(1); setLifecycle(e.target.value as KnowledgeLifecycleStatus | ""); }}><option value="">All</option><option>Draft</option><option>Published</option><option>Archived</option></select></label><label>Type<input value={knowledgeType} onChange={e => { setPage(1); setKnowledgeType(e.target.value); }} /></label><button>Search</button></form>
    {error && <p role="alert">{error}</p>}
    <ol>{result.items.map(item => <li key={item.recordId}><button onClick={() => void open(item.recordId)}><strong>{item.title}</strong><span>{item.lifecycleStatus} - {item.authorityLevel} - {item.freshnessStatus}</span><small>Revision {item.currentRevisionNumber}{item.isAiEligible ? " - AI eligible" : ""}</small></button></li>)}</ol>
    <nav><button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button><span>Page {result.pageNumber} of {Math.max(1, result.totalPages)}</span><button disabled={page >= result.totalPages} onClick={() => setPage(value => value + 1)}>Next</button></nav>
    {selected && <article><h2>{selected.title}</h2><p>{selected.summary}</p><div>{selected.articleBody}</div><small>{selected.lifecycleStatus} - revision {selected.currentRevisionNumber} - {selected.freshnessStatus}</small></article>}
  </section>;
}
```

### Draft, revise, publish, archive, and restore

Every edit creates immutable revision evidence. Update, publish, archive, and restore use the latest `updatedUtc`; after every mutation re-fetch detail before enabling another action. Restoring an old revision creates a new Draft—it does not erase later history.

```
import type { KnowledgeCoreDetail, KnowledgeCoreWrite } from "@buildwithhq/module-sdk";
import { archiveKnowledgeCore, createKnowledgeCore, getKnowledgeCore, publishKnowledgeCore, restoreKnowledgeCoreRevision, updateKnowledgeCore } from "./api";
import type { RecordCreateScope } from "./RecordCreateScopeSelect";
type SharedScope = RecordCreateScope & { isPersonal: false; dataRoleId: number };

export const knowledgeReplacement = (current: KnowledgeCoreDetail): KnowledgeCoreWrite => ({
  expectedUpdatedUtc: current.updatedUtc, slug: current.slug, title: current.title,
  summary: current.summary || "", articleBody: current.articleBody || "", category: current.category || "",
  knowledgeType: current.knowledgeType, authorityLevel: current.authorityLevel,
  locationId: current.locationId || undefined, reviewPolicyId: current.reviewPolicyId || undefined,
  isAiEligible: current.isAiEligible, isSupportEligible: current.isSupportEligible,
});

export function createRunbookDraft(chosenScope: SharedScope) {
  return createKnowledgeCore({ ...chosenScope, slug: "incident-runbook", title: "Incident runbook", articleBody: "Draft steps", knowledgeType: "Procedure", authorityLevel: "Reference", isAiEligible: false, isSupportEligible: false, changeNote: "Initial draft" });
}

export async function revise(current: KnowledgeCoreDetail, articleBody: string) {
  await updateKnowledgeCore(current.recordId, { ...knowledgeReplacement(current), articleBody, changeNote: "Reviewed procedure" });
  return getKnowledgeCore(current.recordId);
}

export async function publish(current: KnowledgeCoreDetail) {
  if (!current.canPublish) throw new Error("The signed-in user cannot publish this item.");
  await publishKnowledgeCore(current.recordId, current.updatedUtc, "Approved for publication");
  return getKnowledgeCore(current.recordId);
}

export async function archive(current: KnowledgeCoreDetail) {
  await archiveKnowledgeCore(current.recordId, current.updatedUtc, "Retired guidance");
  return getKnowledgeCore(current.recordId);
}

export async function restoreAsDraft(current: KnowledgeCoreDetail, knowledgeRevisionId: string) {
  await restoreKnowledgeCoreRevision(current.recordId, knowledgeRevisionId, current.updatedUtc, "Restore for review");
  return getKnowledgeCore(current.recordId);
}
```

### Collections, accountable ownership, and review signoff

One primary owner may be an active tenant user or a DataRole—not both. Assigning ownership never grants record access. Review actions preserve their own optimistic-concurrency timestamp and create/advance the configured Task/Inbox attention.

```
import type { KnowledgeCollection, KnowledgeReviewCycle } from "@buildwithhq/module-sdk";
import { addKnowledgeCoreCollectionItem, beginKnowledgeReview, completeKnowledgeReview, createKnowledgeCoreCollection, getKnowledgeCoreOwners, listKnowledgeCoreCollections, listKnowledgeReviews, reassignKnowledgeReview, removeKnowledgeCoreCollectionItem, removeKnowledgeCoreOwner, setKnowledgeCoreOwner, updateKnowledgeCoreCollection } from "./api";

export const createOperationsCollection = () => createKnowledgeCoreCollection({ name: "Operations", description: "Approved operating procedures", isSupportCollection: true, sortOrder: 10 });

export const renameCollection = (current: KnowledgeCollection, name: string) => updateKnowledgeCoreCollection(current.collectionId, {
  expectedUpdatedUtc: current.updatedUtc, name, description: current.description || "",
  parentCollectionId: current.parentCollectionId || undefined, defaultReviewPolicyId: current.defaultReviewPolicyId || undefined,
  isSupportCollection: current.isSupportCollection, sortOrder: current.sortOrder, isActive: true,
});

export const addToCollection = (collectionId: string, recordId: string) => addKnowledgeCoreCollectionItem(collectionId, recordId, 0);
export const removeFromCollection = (collectionId: string, recordId: string) => removeKnowledgeCoreCollectionItem(collectionId, recordId);
export const makeUserPrimaryOwner = (recordId: string, ownerUserId: string) => setKnowledgeCoreOwner(recordId, { ownerUserId, responsibilityType: "Owner", isPrimary: true });
export const makeRolePrimaryOwner = (recordId: string, dataRoleId: number) => setKnowledgeCoreOwner(recordId, { dataRoleId, responsibilityType: "Owner", isPrimary: true });
export const removeOwner = (knowledgeOwnerId: string) => removeKnowledgeCoreOwner(knowledgeOwnerId);

export async function confirmCurrent(review: KnowledgeReviewCycle) {
  const begun = await beginKnowledgeReview(review.reviewCycleId, review.updatedUtc);
  if (!begun.updatedUtc) throw new Error("Review did not return its concurrency token.");
  return completeKnowledgeReview(review.reviewCycleId, begun.updatedUtc, "ConfirmedCurrent", "Content remains current");
}

export const reassignReviewToRole = (review: KnowledgeReviewCycle, assignedDataRoleId: number) => reassignKnowledgeReview(review.reviewCycleId, review.updatedUtc, { assignedDataRoleId });
export const loadGovernance = () => Promise.all([listKnowledgeCoreCollections(), listKnowledgeReviews()]);
export const loadOwners = (recordId: string) => getKnowledgeCoreOwners(recordId);
```

### Questions, feedback, and measurable gaps

When evidence is missing, record a question instead of generating a confident answer. Repeated questions group inside the same tenant. Answer against an authorized Knowledge record or convert the question into a GeneratedCandidate Draft; it still requires human review and publication before normal RAG can use it.

```
import type { KnowledgeQuestion } from "@buildwithhq/module-sdk";
import { answerKnowledgeQuestion, assignKnowledgeQuestion, convertKnowledgeQuestion, createKnowledgeQuestion, getKnowledgeFeedback, getKnowledgeGaps, listKnowledgeQuestions, recordKnowledgeFeedback } from "./api";
import type { RecordCreateScope } from "./RecordCreateScopeSelect";
type SharedScope = RecordCreateScope & { isPersonal: false; dataRoleId: number };

export const ask = (questionText: string, contextRecordId?: string) => createKnowledgeQuestion(questionText, contextRecordId);
export const assignQuestionToRole = (question: KnowledgeQuestion, assignedDataRoleId: number) => assignKnowledgeQuestion(question.knowledgeQuestionId, question.updatedUtc, { assignedDataRoleId });
export const answerFromKnowledge = (question: KnowledgeQuestion, answerText: string, answerKnowledgeRecordId: string) => answerKnowledgeQuestion(question.knowledgeQuestionId, question.updatedUtc, answerText, answerKnowledgeRecordId);
export const convertToReviewedDraft = (question: KnowledgeQuestion, chosenScope: SharedScope) => convertKnowledgeQuestion(question.knowledgeQuestionId, { ...chosenScope, expectedUpdatedUtc: question.updatedUtc, slug: `question-${question.knowledgeQuestionId}`, title: question.questionText, knowledgeType: "FAQ", authorityLevel: "GeneratedCandidate" });
export const markHelpful = (recordId: string, contextRecordId?: string) => recordKnowledgeFeedback(recordId, "Helpful", undefined, contextRecordId);
export const loadImprovementQueue = (page = 1) => Promise.all([listKnowledgeQuestions("Open", undefined, page, 50), getKnowledgeGaps(undefined, 90, 50)]);
export const loadFeedback = (recordId: string) => getKnowledgeFeedback(recordId);
```

### Optional starter styling

```
.knowledge-core { width: 100%; max-width: none; }
.knowledge-core form, .knowledge-core nav { align-items: end; display: flex; gap: .75rem; }
.knowledge-core ol { list-style: none; margin: 1rem 0; padding: 0; }
.knowledge-core li button { background: transparent; border: 0; display: grid; gap: .2rem; padding: .75rem 0; text-align: left; width: 100%; }
.knowledge-core article { border: 1px solid var(--line, #d8dee8); margin-top: 1rem; padding: 1rem; white-space: pre-wrap; }
```

### Exact lifecycle and supporting routes

| Area | Routes | Canonical procedures |
| --- | --- | --- |
| Items | `GET/POST /api/modules/knowledge-core`; `GET/PUT /{recordId}` | `sp_kc_ListKnowledgeItemsSecured`, `sp_kc_GetKnowledgeItemSecured`, create/update |
| Lifecycle/revisions | `POST /{recordId}/publish`, `/archive`, `/restore`; `GET /revisions` | Publish, archive, immutable history, restore-as-Draft |
| Collections/owners | `/collections`, `/{recordId}/owners`, `/unowned` | `sp_kc_ListCollectionsSecured`, collection membership, secured owner operations |
| Reviews/health | `/reviews`, `/health` | Due-review lifecycle and secured health aggregation |
| Questions/feedback/gaps | `/questions`, `/{recordId}/feedback`, `/gaps` | Evidence-preserving improvement loop |

Lists are bounded to 200 rows per page. AI/RAG eligibility does not grant access: only Published, explicitly eligible content that survives tenant, DataRole, location, record, field, and `CanAiReadRecords` checks enters model context. Generated or support-derived candidates remain Draft until a permitted human publishes them.

## Build a professional Knowledge Core dashboard

These six registry-backed presentation blocks let a designer turn the secured Knowledge Core API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/knowledge-articles`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/knowledge-core-sample.json`, its executable authenticated page at `pages/first-class/knowledge-core-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Knowledge Core projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Published, draft, due-review, stale, and gap counts |
| `entity-list` | `core.entity-list` | Important articles, owners, freshness, and use |
| `progress-list` | `core.progress-list` | Distribution by freshness, lifecycle, category, or owner |
| `series-chart` | `core.series-chart` | Draft, publish, review, use, and gap activity |
| `data-grid` | `core.presentation-grid` | One bounded article page with lifecycle evidence |
| `timeline` | `core.timeline` | Revision, publication, review, retrieval, feedback, gap, and archive |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "knowledge-core-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Knowledge operations",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "published",
            "label": "Published",
            "value": 684,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "review",
            "label": "Review due",
            "value": 31,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "draft",
            "label": "Drafts",
            "value": 24,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "gaps",
            "label": "Open gaps",
            "value": 12,
            "format": "number",
            "tone": "danger"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "knowledge-core-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Knowledge needing attention",
        "hasMore": true,
        "items": [
          {
            "id": "knowledge-core-sample-1",
            "recordId": "knowledge-core-record-1",
            "primary": "Escalation playbook",
            "secondary": "Support operations - owner: Maya Chen",
            "status": {
              "key": "review-due",
              "label": "Review due",
              "tone": "warning"
            },
            "trailing": "14 uses"
          },
          {
            "id": "knowledge-core-sample-2",
            "recordId": "knowledge-core-record-2",
            "primary": "Escalation playbook - Follow-up",
            "secondary": "Support operations - owner: Maya Chen - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "knowledge-core-sample-3",
            "recordId": "knowledge-core-record-3",
            "primary": "Escalation playbook - West region",
            "secondary": "Support operations - owner: Maya Chen - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "knowledge-core-sample-4",
            "recordId": "knowledge-core-record-4",
            "primary": "Escalation playbook - Customer response",
            "secondary": "Support operations - owner: Maya Chen - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "knowledge-core-sample-5",
            "recordId": "knowledge-core-record-5",
            "primary": "Escalation playbook - Regional operations review with a deliberately long title",
            "secondary": "Support operations - owner: Maya Chen - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "knowledge-core-sample-6",
            "recordId": "knowledge-core-record-6",
            "primary": "Escalation playbook - Completed preview",
            "secondary": "Support operations - owner: Maya Chen - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "knowledge-core-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Knowledge freshness",
        "items": [
          {
            "key": "current",
            "label": "Current",
            "value": 611,
            "maximum": 684,
            "displayValue": "611",
            "tone": "success",
            "status": {
              "key": "current",
              "label": "Current",
              "tone": "success"
            }
          },
          {
            "key": "due",
            "label": "Due soon",
            "value": 42,
            "maximum": 684,
            "displayValue": "42",
            "tone": "warning",
            "status": {
              "key": "due",
              "label": "Due soon",
              "tone": "warning"
            }
          },
          {
            "key": "stale",
            "label": "Stale",
            "value": 31,
            "maximum": 684,
            "displayValue": "31",
            "tone": "danger",
            "status": {
              "key": "stale",
              "label": "Stale",
              "tone": "danger"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "knowledge-core-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Knowledge lifecycle",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Published",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Reviewed",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "knowledge-core-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Authorized knowledge",
        "columns": [
          {
            "key": "article",
            "label": "Article",
            "type": "text",
            "align": "left"
          },
          {
            "key": "owner",
            "label": "Owner",
            "type": "text",
            "align": "left"
          },
          {
            "key": "freshness",
            "label": "Freshness",
            "type": "status",
            "align": "left"
          },
          {
            "key": "uses",
            "label": "Uses",
            "type": "number",
            "align": "right"
          },
          {
            "key": "review",
            "label": "Next review",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "knowledge-core-row-1",
            "recordId": "knowledge-core-record-1",
            "cells": {
              "article": "Escalation playbook",
              "owner": "Maya Chen",
              "freshness": {
                "key": "due",
                "label": "Review due",
                "tone": "warning"
              },
              "uses": 14,
              "review": "2026-09-10T00:00:00Z"
            }
          },
          {
            "id": "knowledge-core-row-2",
            "recordId": "knowledge-core-record-2",
            "cells": {
              "article": "Escalation playbook - Follow-up",
              "owner": "Maya Chen",
              "freshness": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "uses": 15,
              "review": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "knowledge-core-row-3",
            "recordId": "knowledge-core-record-3",
            "cells": {
              "article": "Escalation playbook - West region",
              "owner": "Maya Chen",
              "freshness": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "uses": 16,
              "review": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "knowledge-core-row-4",
            "recordId": "knowledge-core-record-4",
            "cells": {
              "article": "Escalation playbook - Customer response",
              "owner": "Maya Chen",
              "freshness": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "uses": 17,
              "review": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "knowledge-core-row-5",
            "recordId": "knowledge-core-record-5",
            "cells": {
              "article": "Escalation playbook - Regional operations review with a deliberately long title",
              "owner": "Maya Chen - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "freshness": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "uses": 18,
              "review": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "knowledge-core-row-6",
            "recordId": "knowledge-core-record-6",
            "cells": {
              "article": "Escalation playbook - Completed preview",
              "owner": "Maya Chen",
              "freshness": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "uses": 19,
              "review": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 684,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "knowledge-core-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Knowledge activity",
        "hasMore": true,
        "items": [
          {
            "id": "knowledge-core-event-1",
            "recordId": "knowledge-core-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Review requested",
            "description": "Escalation playbook entered its scheduled review window.",
            "actor": "Knowledge Core",
            "tone": "warning"
          },
          {
            "id": "knowledge-core-event-2",
            "recordId": "knowledge-core-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Review requested - Follow-up",
            "description": "Escalation playbook entered its scheduled review window. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "knowledge-core-event-3",
            "recordId": "knowledge-core-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Review requested - West region",
            "description": "Escalation playbook entered its scheduled review window. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "knowledge-core-event-4",
            "recordId": "knowledge-core-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Review requested - Customer response",
            "description": "Escalation playbook entered its scheduled review window. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "knowledge-core-event-5",
            "recordId": "knowledge-core-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Review requested - Regional operations review with a deliberately long title",
            "description": "Escalation playbook entered its scheduled review window. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "knowledge-core-event-6",
            "recordId": "knowledge-core-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Review requested - Completed preview",
            "description": "Escalation playbook entered its scheduled review window. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface KnowledgeCorePresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface KnowledgeCorePresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: KnowledgeCorePresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function KnowledgeCorePresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: KnowledgeCorePresentationProps) {
  if (error) return <p role="alert">The Knowledge Core presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Knowledge Core presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Knowledge Core</p>
        <h1>Knowledge operations</h1>
        <p>Published knowledge, review freshness, ownership, gaps, retrieval use, and lifecycle evidence.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/knowledge-articles`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "knowledge-core-live",
      "_type": "module.knowledge-articles",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Start with a few high-value collections, one accountable owner per item, and a practical review interval. Mark content AI-eligible only when its audience, authority, source, and freshness are suitable for model context; missing evidence should create a question, not a confident guess.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/knowledge-core.html).

---
title: "Web links"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/web-links.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Web links

Maintains searchable, categorized, location-aware external links with descriptions, custom fields, relationships, activity, and favorites.

## In brief

- **Runtime key:** module.web-links
- **Experience:** Curated external resources
- **Security:** Server-enforced

Use Web Links to curate external tools, reference sites, customer resources, vendor portals, or research alongside the records and teams that use them.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.web-links. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Maintains searchable, categorized, location-aware external links with descriptions, custom fields, relationships, activity, and favorites.

## Key capabilities

- Search links and filter them by category.
- Create and edit title, URL, description, category, and custom fields.
- Open only contract-validated HTTP or HTTPS destinations in an isolated browsing context.
- Relate and favorite links while preserving location-aware access.

## Common uses

- Team resource directories.
- Customer/vendor portals and external documentation.
- Research links connected to cases, projects, accounts, or knowledge.

## How it connects

Links can relate to Knowledge Articles, Contacts, projects, and dynamic records. They store the reference and business context, not credentials or an embedded authenticated browser session.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

The server accepts strict host-based HTTP(S) URLs without embedded credentials. The runtime opens destinations with an isolated external context and applies normal tenant, DataRole, and location checks to the link record.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.web-links` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

### Explicit scope for create helpers

The native create helpers below require the user's current choice of Personal or one eligible DataRole. In a tenant-runtime component, render `RecordCreateScopeSelect allowAll` from `./RecordCreateScopeSelect` and read its submitted form with `readRecordCreateScope`. Pass that choice to the helper; do not infer it from the page, menu, role count, or a default location. When active locations exist, explicitly choose an authorized location or All when permitted; Personal has no location. For a shared-only helper, validate the returned choice is shared and has a DataRole before calling it. The typed choice is a request, and SQL rechecks current authority. Child actions keep their reviewed parent scope. Ordinary edits preserve the loaded scope and revision; moving scope is a separate explicit action.

## Copy/paste the Web Links page

The native block includes secured search/category browsing, create/edit, detail, custom fields, relation/activity counts, isolated external opening, and favorites:

```
{
  "blocks": [
    { "_id": "resource-links", "_type": "module.web-links", "props": {}, "children": [] }
  ]
}
```

### Custom unstyled links directory

```
import { FormEvent, useEffect, useState } from "react";
import type { WebLinkDetail, WebLinksList } from "@buildwithhq/module-sdk";
import { getWebLink, listWebLinks } from "./api";

const empty: WebLinksList = { contractVersion: 1, pageNumber: 1, pageSize: 50, totalRecords: 0, totalPages: 0, canCreate: false, canEdit: false, items: [] };

export function UnstyledWebLinks({ category = "", locationId = "" }) {
  const [draft, setDraft] = useState(""); const [search, setSearch] = useState(""); const [page, setPage] = useState(1);
  const [result, setResult] = useState<WebLinksList>(empty); const [selected, setSelected] = useState<WebLinkDetail | null>(null);
  useEffect(() => { const controller = new AbortController(); listWebLinks(search, category, controller.signal, locationId, page, 50).then(setResult); return () => controller.abort(); }, [category, locationId, page, search]);
  function submit(event: FormEvent) { event.preventDefault(); setPage(1); setSearch(draft.trim()); }
  async function open(recordId: string) { setSelected(await getWebLink(recordId)); }
  return <section className="custom-links"><h1>Resources</h1><form onSubmit={submit} role="search"><label>Search<input value={draft} onChange={e => setDraft(e.target.value)} /></label><button>Search</button></form>
    <ul>{result.items.map(link => <li key={link.recordId}><button onClick={() => void open(link.recordId)}><strong>{link.title}</strong><span>{link.category || "Uncategorized"}</span></button></li>)}</ul>
    <nav><button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button><span>Page {result.pageNumber} of {Math.max(1, result.totalPages)}</span><button disabled={page >= result.totalPages} onClick={() => setPage(value => value + 1)}>Next</button></nav>
    {selected && <article><h2>{selected.title}</h2><p>{selected.description}</p><a href={selected.url} target="_blank" rel="noopener noreferrer">Open external resource</a></article>}
  </section>;
}
```

### Create, replace, and favorite links

Only absolute HTTP/HTTPS URLs with a real host and no embedded username/password are accepted. Use a managed connector for credentials. Updates are full optimistic replacements.

```
import type { WebLinkDetail, WebLinkDynamicField } from "@buildwithhq/module-sdk";
import { createWebLink, getWebLink, setWebLinkFavorite, updateWebLink } from "./api";
import type { RecordCreateScope } from "./RecordCreateScopeSelect";

const fields = (current: WebLinkDetail) => current.dynamicFields.map((field: WebLinkDynamicField) => ({ fieldKey: field.fieldKey, valueText: field.valueText ?? undefined, valueInt: field.valueInt ?? undefined, valueDecimal: field.valueDecimal ?? undefined, valueDateTime: field.valueDateTime ?? undefined, valueBool: field.valueBool ?? undefined, valueGuid: field.valueGuid ?? undefined, valueJson: field.valueJson }));

export const addDocumentation = (chosenScope: RecordCreateScope) => createWebLink({ ...chosenScope, title: "Product documentation", url: "https://docs.example.com/", category: "Reference", description: "Public product documentation" });
export async function renameLink(current: WebLinkDetail, title: string) { await updateWebLink(current.recordId, { expectedUpdatedUtc: current.updatedUtc, title, url: current.url, description: current.description || "", category: current.category || "", locationId: current.locationId || undefined, dynamicFields: fields(current) }); return getWebLink(current.recordId); }
export async function toggleLinkFavorite(current: WebLinkDetail) { await setWebLinkFavorite(current.recordId, !current.isFavorite); return getWebLink(current.recordId); }
```

### Optional styling

```
.custom-links { width: 100%; max-width: none; }
.custom-links form, .custom-links nav { display: flex; gap: .75rem; }
.custom-links ul { list-style: none; margin: 1rem 0; padding: 0; }
.custom-links li button { background: transparent; border: 0; display: grid; padding: .75rem 0; text-align: left; width: 100%; }
.custom-links article { border: 1px solid var(--line, #d8dee8); margin-top: 1rem; padding: 1rem; }
```

### Exact data path

`GET /api/modules/web-links` and `GET /{recordId}` use `sp_WebLinks_ListSecured` and `sp_WebLinks_GetSecured`. `POST`, `PUT /{recordId}`, and `PUT /{recordId}/favorite` use the reviewed create, update, and favorite procedures. Pages are capped at 200 rows; URL is capped at 1,000 characters, title at 300, and dynamic fields at 200.

## Build a professional Web links dashboard

These six registry-backed presentation blocks let a designer turn the secured Web links API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/web-links`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/web-links-sample.json`, its executable authenticated page at `pages/first-class/web-links-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Web links projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Active, new, favorite, and review-due counts |
| `entity-list` | `core.entity-list` | Recently added or maintained authorized links |
| `progress-list` | `core.progress-list` | Distribution by category, owner, or state |
| `series-chart` | `core.series-chart` | Link creation and maintenance over time |
| `data-grid` | `core.presentation-grid` | One bounded link page with safe display URLs |
| `timeline` | `core.timeline` | Create, edit, favorite, relate, review, and archive events |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "web-links-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Web link library",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "active",
            "label": "Active links",
            "value": 238,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "new",
            "label": "Added this month",
            "value": 17,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "favorites",
            "label": "Your favorites",
            "value": 14,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "review",
            "label": "Review due",
            "value": 8,
            "format": "number",
            "tone": "danger"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "web-links-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Recently updated links",
        "hasMore": true,
        "items": [
          {
            "id": "web-links-sample-1",
            "recordId": "web-links-record-1",
            "primary": "Field safety portal",
            "secondary": "Operations - docs.example.test",
            "status": {
              "key": "active",
              "label": "Active",
              "tone": "success"
            },
            "trailing": "Favorite"
          },
          {
            "id": "web-links-sample-2",
            "recordId": "web-links-record-2",
            "primary": "Field safety portal - Follow-up",
            "secondary": "Operations - docs.example.test - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "web-links-sample-3",
            "recordId": "web-links-record-3",
            "primary": "Field safety portal - West region",
            "secondary": "Operations - docs.example.test - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "web-links-sample-4",
            "recordId": "web-links-record-4",
            "primary": "Field safety portal - Customer response",
            "secondary": "Operations - docs.example.test - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "web-links-sample-5",
            "recordId": "web-links-record-5",
            "primary": "Field safety portal - Regional operations review with a deliberately long title",
            "secondary": "Operations - docs.example.test - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "web-links-sample-6",
            "recordId": "web-links-record-6",
            "primary": "Field safety portal - Completed preview",
            "secondary": "Operations - docs.example.test - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "web-links-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Links by category",
        "items": [
          {
            "key": "operations",
            "label": "Operations",
            "value": 96,
            "maximum": 238,
            "displayValue": "96",
            "tone": "primary",
            "status": {
              "key": "operations",
              "label": "Operations",
              "tone": "primary"
            }
          },
          {
            "key": "sales",
            "label": "Sales",
            "value": 74,
            "maximum": 238,
            "displayValue": "74",
            "tone": "success",
            "status": {
              "key": "sales",
              "label": "Sales",
              "tone": "success"
            }
          },
          {
            "key": "support",
            "label": "Support",
            "value": 68,
            "maximum": 238,
            "displayValue": "68",
            "tone": "warning",
            "status": {
              "key": "support",
              "label": "Support",
              "tone": "warning"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "web-links-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Link maintenance",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Added",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Updated",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "web-links-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Authorized web links",
        "columns": [
          {
            "key": "name",
            "label": "Link",
            "type": "text",
            "align": "left"
          },
          {
            "key": "host",
            "label": "Host",
            "type": "text",
            "align": "left"
          },
          {
            "key": "category",
            "label": "Category",
            "type": "text",
            "align": "left"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "updated",
            "label": "Updated",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "web-links-row-1",
            "recordId": "web-links-record-1",
            "cells": {
              "name": "Field safety portal",
              "host": "docs.example.test",
              "category": "Operations",
              "status": {
                "key": "active",
                "label": "Active",
                "tone": "success"
              },
              "updated": "2026-09-04T13:20:00Z"
            }
          },
          {
            "id": "web-links-row-2",
            "recordId": "web-links-record-2",
            "cells": {
              "name": "Field safety portal - Follow-up",
              "host": "docs.example.test",
              "category": "Operations",
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "updated": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "web-links-row-3",
            "recordId": "web-links-record-3",
            "cells": {
              "name": "Field safety portal - West region",
              "host": "docs.example.test",
              "category": "Operations",
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "updated": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "web-links-row-4",
            "recordId": "web-links-record-4",
            "cells": {
              "name": "Field safety portal - Customer response",
              "host": "docs.example.test",
              "category": "Operations",
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "updated": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "web-links-row-5",
            "recordId": "web-links-record-5",
            "cells": {
              "name": "Field safety portal - Regional operations review with a deliberately long title",
              "host": "docs.example.test - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "category": "Operations",
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "updated": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "web-links-row-6",
            "recordId": "web-links-record-6",
            "cells": {
              "name": "Field safety portal - Completed preview",
              "host": "docs.example.test",
              "category": "Operations",
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "updated": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 238,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "web-links-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Link activity",
        "hasMore": true,
        "items": [
          {
            "id": "web-links-event-1",
            "recordId": "web-links-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Web link updated",
            "description": "The Field safety portal description was refreshed.",
            "actor": "Jordan Lee",
            "tone": "neutral"
          },
          {
            "id": "web-links-event-2",
            "recordId": "web-links-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Web link updated - Follow-up",
            "description": "The Field safety portal description was refreshed. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "web-links-event-3",
            "recordId": "web-links-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Web link updated - West region",
            "description": "The Field safety portal description was refreshed. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "web-links-event-4",
            "recordId": "web-links-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Web link updated - Customer response",
            "description": "The Field safety portal description was refreshed. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "web-links-event-5",
            "recordId": "web-links-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Web link updated - Regional operations review with a deliberately long title",
            "description": "The Field safety portal description was refreshed. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "web-links-event-6",
            "recordId": "web-links-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Web link updated - Completed preview",
            "description": "The Field safety portal description was refreshed. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface WebLinksPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface WebLinksPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: WebLinksPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function WebLinksPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: WebLinksPresentationProps) {
  if (error) return <p role="alert">The Web links presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Web links presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Web links</p>
        <h1>Web link library</h1>
        <p>Authorized links, categories, ownership, favorites, and recent maintenance.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/web-links`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "web-links-live",
      "_type": "module.web-links",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Store the public destination only. If an integration needs OAuth or an API secret, use a managed connector instead of putting credentials in a URL.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/web-links.html).

---
title: "Chat rooms"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/chat-rooms.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Chat rooms

Provides secured team rooms with messages, unread state, membership, room administration, mute settings, reactions, archives, custom fields, relations, activity, and favorites.

## In brief

- **Runtime key:** module.chat-rooms
- **Experience:** Members-only team discussion
- **Security:** Server-enforced

Use Chat Rooms for ongoing team conversation where membership, unread state, lightweight reactions, and room administration matter more than a formal topic hierarchy.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.chat-rooms. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Provides secured team rooms with messages, unread state, membership, room administration, mute settings, reactions, archives, custom fields, relations, activity, and favorites.

## Key capabilities

- Search active or archived rooms and see unread counts.
- Create/edit rooms, post messages, and react with bounded reaction types.
- Manage members, room administrators, mute state, and archive state when authorized.
- Show location, dynamic fields, related records, activity, and favorites.

## Common uses

- Project or operations team chat.
- Location, department, incident, or customer team rooms.
- Informal collaboration adjacent to records that retain the formal work state.

## How it connects

Rooms can relate to projects, customers, incidents, Files, and other Records. Use Conversations for durable customer/channel threads and Discussion Boards for structured topics; Chat Rooms remain the fast team discussion surface.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Rooms are shared-only: explicitly select one eligible DataRole and an authorized location or All when available. Room and message reads require current membership plus DataRole/location access, including Graph, Activity, Favorites and direct record links. Native Chat Rooms search remains available; general and AI search exclude chat content. Saves recheck current authority. Member administration, room edits and archiving require the appropriate room capability; members can post and edit their own messages without gaining room-administration rights.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.chat-rooms` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

## Copy/paste the Chat Rooms page

The native block includes rooms, unread state, create/edit/archive, membership and mute administration, messages, replies, file references, reactions, custom fields, relations, activity, and favorites. Each action remains subject to the current actor's record and room permissions.

**Availability limits:** the current native composer sends no mentions; accepting mention IDs in a message contract does not establish mention selection or notification delivery. Attachment upload controls exist, but attachment metadata/content authorization and delivery need their own acceptance. Generic search, AI, graph and export room-membership coverage also remains under security review; this page is not certification of those paths.

```
{
  "blocks": [
    { "_id": "team-chat", "_type": "module.chat-rooms", "props": {}, "children": [] }
  ]
}
```

### Custom unstyled room and message view

Opening a room deliberately marks its latest visible message read for the current user. The server still applies record and membership scope before returning content.

```
import { FormEvent, useEffect, useState } from "react";
import type { ChatRoomDetail, ChatRoomsList } from "@buildwithhq/module-sdk";
import { getChatRoom, listChatRooms, markChatRoomRead, postChatMessage } from "./api";

const empty: ChatRoomsList = { contractVersion: 1, pageNumber: 1, pageSize: 50, totalRecords: 0, totalPages: 0, canCreate: false, items: [] };
export function UnstyledChatRooms({ locationId = "" }) {
  const [draft, setDraft] = useState(""); const [search, setSearch] = useState(""); const [page, setPage] = useState(1);
  const [rooms, setRooms] = useState<ChatRoomsList>(empty); const [selected, setSelected] = useState<ChatRoomDetail | null>(null);
  useEffect(() => { const controller = new AbortController(); listChatRooms(search, false, controller.signal, locationId, page, 50).then(setRooms); return () => controller.abort(); }, [locationId, page, search]);
  async function open(recordId: string) { const detail = await getChatRoom(recordId); setSelected(detail); await markChatRoomRead(recordId); }
  async function send(event: FormEvent<HTMLFormElement>) { event.preventDefault(); if (!selected?.canPost) return; const form = event.currentTarget; const text = String(new FormData(form).get("message") || ""); await postChatMessage(selected.recordId, { messageText: text, mentionedUserIds: [] }); form.reset(); setSelected(await getChatRoom(selected.recordId)); }
  return <section className="custom-chat"><h1>Team chat</h1><form role="search" onSubmit={e => { e.preventDefault(); setPage(1); setSearch(draft.trim()); }}><input aria-label="Search rooms" value={draft} onChange={e => setDraft(e.target.value)} /><button>Search</button></form>
    <ul>{rooms.items.map(room => <li key={room.recordId}><button onClick={() => void open(room.recordId)}><strong>{room.roomName}</strong><span>{room.memberCount} members - {room.unreadCount} unread</span><small>{room.lastMessageText || "No messages"}</small></button></li>)}</ul>
    <nav><button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button><span>Page {rooms.pageNumber} of {Math.max(1, rooms.totalPages)}</span><button disabled={page >= rooms.totalPages} onClick={() => setPage(value => value + 1)}>Next</button></nav>
    {selected && <article><h2>{selected.roomName}</h2>{selected.messages.map(message => <p key={message.chatMessageId}><strong>{message.postedByDisplayName || "Member"}</strong>: {message.messageText}</p>)}{selected.canPost && <form onSubmit={send}><label>Message<textarea name="message" required maxLength={20000} /></label><button>Send</button></form>}</article>}
  </section>;
}
```

### Create, administer, react, and attach proof

Room replacement uses `expectedUpdatedUtc`. Personal scope is not available for Chat Rooms. Creation requires an explicit authorized DataRole choice with `isPersonal: false`. When active locations exist, select one authorized location or explicitly choose All if you have all-location access. Omit the location choice only when no active locations exist. Never derive these choices from a menu, sole role or default. The server rechecks authority when saving. Member changes require room administration; a tenant-user ID is a target and is revalidated. The message contract accepts up to 50 unique mention IDs and one File ID; this does not establish mention notification or attachment delivery acceptance. Reactions are exactly `like`, `love`, `celebrate`, `insightful`, or `ack`.

```
import type { ChatRoomDetail } from "@buildwithhq/module-sdk";
import { createChatRoom, getChatRoom, postChatMessage, setChatReaction, setChatRoomFavorite, setChatRoomMember, updateChatRoom } from "./api";

const roomFields = (room: ChatRoomDetail) => room.dynamicFields.map(field => ({ fieldKey: field.fieldKey, valueText: field.valueText, valueInt: field.valueInt, valueDecimal: field.valueDecimal, valueDateTime: field.valueDateTime, valueBool: field.valueBool, valueGuid: field.valueGuid, valueJson: field.valueJson }));
// Collect this from the secured scope selector; do not supply inferred defaults.
type ChosenRoomScope = { isPersonal: false; dataRoleId: number } & (
  | { locationScope: "Specific"; locationId: string }
  | { locationScope: "All"; locationId?: never }
  | { locationScope?: never; locationId?: never }
);
export const createProjectRoom = (chosenScope: ChosenRoomScope) => createChatRoom({ roomName: "Project team", description: "Daily coordination", roomType: 0, ...chosenScope, dynamicFields: [] });
export async function archiveRoom(room: ChatRoomDetail) { await updateChatRoom(room.recordId, { expectedUpdatedUtc: room.updatedUtc, roomName: room.roomName, description: room.description || "", roomType: room.roomType, isArchived: true, locationId: room.locationId || undefined, dynamicFields: roomFields(room) }); return getChatRoom(room.recordId); }
export async function addMember(room: ChatRoomDetail, memberUserId: string, isAdmin = false) { await setChatRoomMember(room.recordId, memberUserId, { isMember: true, isAdmin, isMuted: false }); return getChatRoom(room.recordId); }
export async function attachMessage(room: ChatRoomDetail, messageText: string, attachedFileId: string) { await postChatMessage(room.recordId, { messageText, attachedFileId, mentionedUserIds: [] }); return getChatRoom(room.recordId); }
export async function acknowledge(room: ChatRoomDetail, chatMessageId: string, isActive = true) { await setChatReaction(room.recordId, chatMessageId, "ack", isActive); return getChatRoom(room.recordId); }
export async function toggleRoomFavorite(room: ChatRoomDetail) { await setChatRoomFavorite(room.recordId, !room.isFavorite); return getChatRoom(room.recordId); }
```

### Optional styling

```
.custom-chat { width: 100%; max-width: none; }
.custom-chat form, .custom-chat nav { display: flex; gap: .75rem; }
.custom-chat > ul { list-style: none; margin: 1rem 0; padding: 0; }
.custom-chat > ul button { background: transparent; border: 0; display: grid; padding: .75rem 0; text-align: left; width: 100%; }
.custom-chat article { border: 1px solid var(--line, #d8dee8); margin-top: 1rem; padding: 1rem; }
```

### Exact data path

Room administrators can add users who already have the required active DataRole and location access. An eligible user does not gain access until membership is added; removing membership takes effect on subsequent reads and saves, including an existing signed-in session. A stale message revision is rejected; reload the current message before deciding whether to save again.

Removing a room soft-deletes the room and its active messages while retaining their history. Where retention and restore are enabled, an authorized restore brings back messages hidden by that room removal. Messages removed individually remain removed. Use Deleted items for the supported restore action.

`GET/POST /api/modules/chat-rooms`, `GET/PUT /{recordId}`, `POST /{recordId}/messages`, and the `/reaction`, `/members`, `/read`, and `/favorite` actions map to the corresponding `sp_ChatRooms_*Secured` procedures. Lists are at most 200 rooms per page. Room detail returns a bounded message/member view; use a formal record or Conversation when durable workflow/channel semantics are required.

## Build a professional Chat rooms dashboard

These six registry-backed presentation blocks let a designer turn the secured Chat rooms API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/chat-rooms`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/chat-rooms-sample.json`, its executable authenticated page at `pages/first-class/chat-rooms-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Chat rooms projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Accessible rooms, unread rooms, messages, and mentions |
| `entity-list` | `core.entity-list` | Rooms the current member can open |
| `progress-list` | `core.progress-list` | Distribution by activity, membership, or state |
| `series-chart` | `core.series-chart` | Message and active-member volume |
| `data-grid` | `core.presentation-grid` | One bounded member-authorized room page |
| `timeline` | `core.timeline` | Room creation, membership, message, mention, pin, and archive |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "chat-rooms-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Chat room overview",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "rooms",
            "label": "Accessible rooms",
            "value": 28,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "unread",
            "label": "Unread rooms",
            "value": 6,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "messages",
            "label": "Messages today",
            "value": 214,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "mentions",
            "label": "Mentions",
            "value": 9,
            "format": "number",
            "tone": "danger"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "chat-rooms-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Active rooms",
        "hasMore": true,
        "items": [
          {
            "id": "chat-rooms-sample-1",
            "recordId": "chat-rooms-record-1",
            "primary": "Field Operations",
            "secondary": "18 members - 42 messages today",
            "status": {
              "key": "active",
              "label": "Active",
              "tone": "success"
            },
            "trailing": "3 unread"
          },
          {
            "id": "chat-rooms-sample-2",
            "recordId": "chat-rooms-record-2",
            "primary": "Field Operations - Follow-up",
            "secondary": "18 members - 42 messages today - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "chat-rooms-sample-3",
            "recordId": "chat-rooms-record-3",
            "primary": "Field Operations - West region",
            "secondary": "18 members - 42 messages today - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "chat-rooms-sample-4",
            "recordId": "chat-rooms-record-4",
            "primary": "Field Operations - Customer response",
            "secondary": "18 members - 42 messages today - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "chat-rooms-sample-5",
            "recordId": "chat-rooms-record-5",
            "primary": "Field Operations - Regional operations review with a deliberately long title",
            "secondary": "18 members - 42 messages today - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "chat-rooms-sample-6",
            "recordId": "chat-rooms-record-6",
            "primary": "Field Operations - Completed preview",
            "secondary": "18 members - 42 messages today - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "chat-rooms-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Rooms by activity",
        "items": [
          {
            "key": "high",
            "label": "High activity",
            "value": 7,
            "maximum": 28,
            "displayValue": "7",
            "tone": "primary",
            "status": {
              "key": "high",
              "label": "High activity",
              "tone": "primary"
            }
          },
          {
            "key": "normal",
            "label": "Normal",
            "value": 15,
            "maximum": 28,
            "displayValue": "15",
            "tone": "success",
            "status": {
              "key": "normal",
              "label": "Normal",
              "tone": "success"
            }
          },
          {
            "key": "quiet",
            "label": "Quiet",
            "value": 6,
            "maximum": 28,
            "displayValue": "6",
            "tone": "neutral",
            "status": {
              "key": "quiet",
              "label": "Quiet",
              "tone": "neutral"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "chat-rooms-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Chat activity",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Messages",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Active members",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "chat-rooms-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Accessible chat rooms",
        "columns": [
          {
            "key": "room",
            "label": "Room",
            "type": "text",
            "align": "left"
          },
          {
            "key": "members",
            "label": "Members",
            "type": "number",
            "align": "right"
          },
          {
            "key": "unread",
            "label": "Unread",
            "type": "number",
            "align": "right"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "updated",
            "label": "Last activity",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "chat-rooms-row-1",
            "recordId": "chat-rooms-record-1",
            "cells": {
              "room": "Field Operations",
              "members": 18,
              "unread": 3,
              "status": {
                "key": "active",
                "label": "Active",
                "tone": "success"
              },
              "updated": "2026-09-04T17:51:00Z"
            }
          },
          {
            "id": "chat-rooms-row-2",
            "recordId": "chat-rooms-record-2",
            "cells": {
              "room": "Field Operations - Follow-up",
              "members": 19,
              "unread": 4,
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "updated": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "chat-rooms-row-3",
            "recordId": "chat-rooms-record-3",
            "cells": {
              "room": "Field Operations - West region",
              "members": 20,
              "unread": 5,
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "updated": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "chat-rooms-row-4",
            "recordId": "chat-rooms-record-4",
            "cells": {
              "room": "Field Operations - Customer response",
              "members": 21,
              "unread": 6,
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "updated": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "chat-rooms-row-5",
            "recordId": "chat-rooms-record-5",
            "cells": {
              "room": "Field Operations - Regional operations review with a deliberately long title",
              "members": 22,
              "unread": 7,
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "updated": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "chat-rooms-row-6",
            "recordId": "chat-rooms-record-6",
            "cells": {
              "room": "Field Operations - Completed preview",
              "members": 23,
              "unread": 8,
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "updated": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 28,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "chat-rooms-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Room activity",
        "hasMore": true,
        "items": [
          {
            "id": "chat-rooms-event-1",
            "recordId": "chat-rooms-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Message posted",
            "description": "A schedule update was posted in Field Operations.",
            "actor": "Maya Chen",
            "tone": "primary"
          },
          {
            "id": "chat-rooms-event-2",
            "recordId": "chat-rooms-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Message posted - Follow-up",
            "description": "A schedule update was posted in Field Operations. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "chat-rooms-event-3",
            "recordId": "chat-rooms-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Message posted - West region",
            "description": "A schedule update was posted in Field Operations. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "chat-rooms-event-4",
            "recordId": "chat-rooms-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Message posted - Customer response",
            "description": "A schedule update was posted in Field Operations. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "chat-rooms-event-5",
            "recordId": "chat-rooms-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Message posted - Regional operations review with a deliberately long title",
            "description": "A schedule update was posted in Field Operations. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "chat-rooms-event-6",
            "recordId": "chat-rooms-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Message posted - Completed preview",
            "description": "A schedule update was posted in Field Operations. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface ChatRoomsPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface ChatRoomsPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: ChatRoomsPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function ChatRoomsPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: ChatRoomsPresentationProps) {
  if (error) return <p role="alert">The Chat rooms presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Chat rooms presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Chat rooms</p>
        <h1>Chat room overview</h1>
        <p>Accessible rooms, unread work, membership, message volume, and recent collaboration.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/chat-rooms`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "chat-rooms-live",
      "_type": "module.chat-rooms",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Use rooms for conversation, not as the only place a decision or task exists. Promote important outcomes into the appropriate record, workflow, or activity trail.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/chat-rooms.html).

---
title: "Discussion Boards"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/discussion-boards.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Discussion Boards

Provides boards, topics, threaded posts, replies, pin/lock moderation, archives, owned-post editing, custom fields, relations, activity, and favorites.

## In brief

- **Runtime key:** module.discussion-boards
- **Experience:** Structured community discussion
- **Security:** Server-enforced

Use Discussion Boards when collaboration needs named boards, durable topics, threaded replies, and moderation rather than a continuous chat stream.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.discussion-boards. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Provides boards, topics, threaded posts, replies, pin/lock moderation, archives, owned-post editing, custom fields, relations, activity, and favorites.

## Key capabilities

- Search active or archived boards and browse topic/post counts.
- Create boards and topics, reply to topics, and edit owned or otherwise authorized content.
- Pin or lock topics and archive boards with the required moderation capability.
- Favorite boards/topics and show secured relations, activity, location, and dynamic fields.

## Common uses

- Customer or partner communities.
- Internal Q&A, proposals, and long-running technical discussions.
- Program, project, or policy forums that benefit from topic-level history.

## How it connects

Boards and topics can relate to Knowledge Articles, Files, projects, products, or cases. A resolved discussion can become maintained knowledge while the original thread remains available as evidence.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Board, topic, and post operations enforce tenant, DataRole, location, ownership, and moderation rules. Locked topics refuse ordinary replies, and edit controls reflect secured response capabilities.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.discussion-boards` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

### Explicit scope for create helpers

The native create helpers below require the user's current choice of one eligible DataRole with `isPersonal: false`. In a tenant-runtime component, render `RecordCreateScopeSelect allowAll allowPersonal={false}` from `./RecordCreateScopeSelect` and read its submitted form with `readRecordCreateScope`. Pass that choice to the helper; do not infer it from the page, menu, role count, or a default location. When active locations exist, explicitly choose an authorized location or All when permitted; Personal has no location. For a shared-only helper, validate the returned choice is shared and has a DataRole before calling it. The typed choice is a request, and SQL rechecks current authority. Child actions keep their reviewed parent scope. Ordinary edits preserve the loaded scope and revision; moving scope is a separate explicit action.

## Copy/paste the Discussion Boards page

The native block supplies secured board search, board/topic/post detail, create/edit, topic pin/lock moderation, replies, archive state, custom fields, relations, activity, and favorites:

```
{
  "blocks": [
    { "_id": "community-discussions", "_type": "module.discussion-boards", "props": {}, "children": [] }
  ]
}
```

### Custom unstyled board and topic browser

```
import { FormEvent, useEffect, useState } from "react";
import type { DiscussionBoardDetail, DiscussionBoardsList, DiscussionTopicDetail } from "@buildwithhq/module-sdk";
import { getDiscussionBoard, getDiscussionTopic, listDiscussionBoards } from "./api";

const empty: DiscussionBoardsList = { contractVersion: 1, pageNumber: 1, pageSize: 50, totalRecords: 0, totalPages: 0, canCreate: false, canEdit: false, items: [] };
export function UnstyledDiscussionBoards({ locationId = "" }) {
  const [draft, setDraft] = useState(""); const [search, setSearch] = useState(""); const [page, setPage] = useState(1);
  const [boards, setBoards] = useState<DiscussionBoardsList>(empty); const [board, setBoard] = useState<DiscussionBoardDetail | null>(null); const [topic, setTopic] = useState<DiscussionTopicDetail | null>(null);
  useEffect(() => { const controller = new AbortController(); listDiscussionBoards(search, false, controller.signal, locationId, page, 50).then(setBoards); return () => controller.abort(); }, [locationId, page, search]);
  async function openBoard(recordId: string) { setBoard(await getDiscussionBoard(recordId)); setTopic(null); }
  async function openTopic(recordId: string) { setTopic(await getDiscussionTopic(recordId)); }
  return <section className="custom-boards"><h1>Discussion Boards</h1><form role="search" onSubmit={(e: FormEvent) => { e.preventDefault(); setPage(1); setSearch(draft.trim()); }}><input aria-label="Search boards" value={draft} onChange={e => setDraft(e.target.value)} /><button>Search</button></form>
    <ul>{boards.items.map(item => <li key={item.recordId}><button onClick={() => void openBoard(item.recordId)}><strong>{item.boardName}</strong><span>{item.topicCount} topics - {item.postCount} posts</span></button></li>)}</ul>
    <nav><button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button><span>Page {boards.pageNumber} of {Math.max(1, boards.totalPages)}</span><button disabled={page >= boards.totalPages} onClick={() => setPage(value => value + 1)}>Next</button></nav>
    {board && <article><h2>{board.boardName}</h2><p>{board.description}</p><ol>{board.topics.map(item => <li key={item.recordId}><button onClick={() => void openTopic(item.recordId)}>{item.isPinned ? "Pinned: " : ""}{item.topicTitle} ({item.postCount})</button></li>)}</ol></article>}
    {topic && <article><h2>{topic.topicTitle}</h2>{topic.posts.map(post => <section key={post.recordId}><strong>{post.postedByDisplayName || "Member"}</strong><p>{post.postBody}</p></section>)}</article>}
  </section>;
}
```

### Create boards and topics, moderate, reply, and edit

Board, topic, and post edits are separate optimistic commands. Locked topics refuse ordinary replies; archived boards refuse new work. `canEdit`, `canCreateTopic`, `canReply`, and each post's `canEdit` are server decisions.

```
import type { DiscussionBoardDetail, DiscussionPost, DiscussionTopicDetail } from "@buildwithhq/module-sdk";
import { createDiscussionBoard, createDiscussionTopic, getDiscussionBoard, getDiscussionTopic, postDiscussionReply, setDiscussionFavorite, updateDiscussionBoard, updateDiscussionPost, updateDiscussionTopic } from "./api";
import type { RecordCreateScope } from "./RecordCreateScopeSelect";
type SharedScope = RecordCreateScope & { isPersonal: false; dataRoleId: number };

export const createBoard = (chosenScope: SharedScope) => createDiscussionBoard({ ...chosenScope, boardName: "Product questions", description: "Durable product discussions", dynamicFields: [] });
export async function archiveBoard(board: DiscussionBoardDetail) { await updateDiscussionBoard(board.recordId, { expectedUpdatedUtc: board.updatedUtc, boardName: board.boardName, description: board.description || "", isArchived: true, locationId: board.locationId || undefined, dynamicFields: board.dynamicFields }); return getDiscussionBoard(board.recordId); }
export const startTopic = (board: DiscussionBoardDetail, topicTitle: string, initialPostBody: string) => createDiscussionTopic(board.recordId, { topicTitle, initialPostBody });
export async function lockTopic(topic: DiscussionTopicDetail) { await updateDiscussionTopic(topic.recordId, { expectedUpdatedUtc: topic.updatedUtc, topicTitle: topic.topicTitle, isPinned: topic.isPinned, isLocked: true }); return getDiscussionTopic(topic.recordId); }
export async function reply(topic: DiscussionTopicDetail, postBody: string, parentDiscussionPostId?: string) { if (!topic.canReply) throw new Error("This topic is closed to replies."); await postDiscussionReply(topic.recordId, { postBody, parentDiscussionPostId }); return getDiscussionTopic(topic.recordId); }
export async function editPost(topic: DiscussionTopicDetail, post: DiscussionPost, postBody: string) { if (!post.canEdit) throw new Error("This post cannot be edited."); await updateDiscussionPost(post.recordId, { expectedUpdatedUtc: post.updatedUtc, postBody }); return getDiscussionTopic(topic.recordId); }
export async function toggleTopicFavorite(topic: DiscussionTopicDetail) { await setDiscussionFavorite(topic.recordId, !topic.isFavorite); return getDiscussionTopic(topic.recordId); }
```

### Optional styling

```
.custom-boards { width: 100%; max-width: none; }
.custom-boards > ul, .custom-boards ol { list-style: none; margin: 1rem 0; padding: 0; }
.custom-boards button { text-align: left; }
.custom-boards > article { border: 1px solid var(--line, #d8dee8); margin-top: 1rem; padding: 1rem; }
.custom-boards article section { border-top: 1px solid var(--line, #d8dee8); padding: .75rem 0; }
```

### Exact data path and current scale boundary

The route family is `/api/modules/discussion-boards`: list/create/update board; `/{boardRecordId}/topics`; `/topics/{recordId}`; `/topics/{topicRecordId}/posts`; `/posts/{recordId}`; and `/records/{recordId}/favorite`. Each maps to an explicit `sp_DiscussionBoards_*Secured` procedure and rechecks tenant, record, location, ownership, lock, archive, and moderation scope.

**Important:** board list pages are capped at 200, but the current board-detail contract returns all visible topics and the topic-detail contract returns all visible posts. Use this module for bounded communities today. Before using it for a forum with very large topics, add measured server pagination to those two detail contracts rather than fetching everything and trimming it in React.

## Build a professional Discussion Boards dashboard

These six registry-backed presentation blocks let a designer turn the secured Discussion Boards API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/discussion-boards`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/discussion-boards-sample.json`, its executable authenticated page at `pages/first-class/discussion-boards-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Discussion Boards projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Visible boards, open topics, unanswered work, and posts |
| `entity-list` | `core.entity-list` | Active topics the user may open |
| `progress-list` | `core.progress-list` | Distribution by topic state, board, or response |
| `series-chart` | `core.series-chart` | New topics, replies, and resolved discussions |
| `data-grid` | `core.presentation-grid` | One bounded topic page with counts and state |
| `timeline` | `core.timeline` | Topic, reply, follow, moderation, answer, lock, and archive |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "discussion-boards-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Discussion overview",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "boards",
            "label": "Visible boards",
            "value": 12,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "topics",
            "label": "Open topics",
            "value": 86,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "unanswered",
            "label": "Unanswered",
            "value": 7,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "posts",
            "label": "Posts this week",
            "value": 143,
            "format": "number",
            "tone": "success"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "discussion-boards-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Active topics",
        "hasMore": true,
        "items": [
          {
            "id": "discussion-boards-sample-1",
            "recordId": "discussion-boards-record-1",
            "primary": "Reducing repeat truck rolls",
            "secondary": "Field service - 12 replies",
            "status": {
              "key": "open",
              "label": "Open",
              "tone": "primary"
            },
            "trailing": "2 new"
          },
          {
            "id": "discussion-boards-sample-2",
            "recordId": "discussion-boards-record-2",
            "primary": "Reducing repeat truck rolls - Follow-up",
            "secondary": "Field service - 12 replies - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "discussion-boards-sample-3",
            "recordId": "discussion-boards-record-3",
            "primary": "Reducing repeat truck rolls - West region",
            "secondary": "Field service - 12 replies - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "discussion-boards-sample-4",
            "recordId": "discussion-boards-record-4",
            "primary": "Reducing repeat truck rolls - Customer response",
            "secondary": "Field service - 12 replies - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "discussion-boards-sample-5",
            "recordId": "discussion-boards-record-5",
            "primary": "Reducing repeat truck rolls - Regional operations review with a deliberately long title",
            "secondary": "Field service - 12 replies - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "discussion-boards-sample-6",
            "recordId": "discussion-boards-record-6",
            "primary": "Reducing repeat truck rolls - Completed preview",
            "secondary": "Field service - 12 replies - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "discussion-boards-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Topics by state",
        "items": [
          {
            "key": "open",
            "label": "Open",
            "value": 86,
            "maximum": 159,
            "displayValue": "86",
            "tone": "primary",
            "status": {
              "key": "open",
              "label": "Open",
              "tone": "primary"
            }
          },
          {
            "key": "answered",
            "label": "Answered",
            "value": 64,
            "maximum": 159,
            "displayValue": "64",
            "tone": "success",
            "status": {
              "key": "answered",
              "label": "Answered",
              "tone": "success"
            }
          },
          {
            "key": "locked",
            "label": "Locked",
            "value": 9,
            "maximum": 159,
            "displayValue": "9",
            "tone": "neutral",
            "status": {
              "key": "locked",
              "label": "Locked",
              "tone": "neutral"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "discussion-boards-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Discussion activity",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Topics",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Posts",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "discussion-boards-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Visible discussion topics",
        "columns": [
          {
            "key": "topic",
            "label": "Topic",
            "type": "text",
            "align": "left"
          },
          {
            "key": "board",
            "label": "Board",
            "type": "text",
            "align": "left"
          },
          {
            "key": "replies",
            "label": "Replies",
            "type": "number",
            "align": "right"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "updated",
            "label": "Updated",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "discussion-boards-row-1",
            "recordId": "discussion-boards-record-1",
            "cells": {
              "topic": "Reducing repeat truck rolls",
              "board": "Field service",
              "replies": 12,
              "status": {
                "key": "open",
                "label": "Open",
                "tone": "primary"
              },
              "updated": "2026-09-04T16:44:00Z"
            }
          },
          {
            "id": "discussion-boards-row-2",
            "recordId": "discussion-boards-record-2",
            "cells": {
              "topic": "Reducing repeat truck rolls - Follow-up",
              "board": "Field service",
              "replies": 13,
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "updated": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "discussion-boards-row-3",
            "recordId": "discussion-boards-record-3",
            "cells": {
              "topic": "Reducing repeat truck rolls - West region",
              "board": "Field service",
              "replies": 14,
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "updated": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "discussion-boards-row-4",
            "recordId": "discussion-boards-record-4",
            "cells": {
              "topic": "Reducing repeat truck rolls - Customer response",
              "board": "Field service",
              "replies": 15,
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "updated": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "discussion-boards-row-5",
            "recordId": "discussion-boards-record-5",
            "cells": {
              "topic": "Reducing repeat truck rolls - Regional operations review with a deliberately long title",
              "board": "Field service - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "replies": 16,
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "updated": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "discussion-boards-row-6",
            "recordId": "discussion-boards-record-6",
            "cells": {
              "topic": "Reducing repeat truck rolls - Completed preview",
              "board": "Field service",
              "replies": 17,
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "updated": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 12,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "discussion-boards-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Discussion activity",
        "hasMore": true,
        "items": [
          {
            "id": "discussion-boards-event-1",
            "recordId": "discussion-boards-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Reply posted",
            "description": "A new field checklist suggestion was added.",
            "actor": "Jordan Lee",
            "tone": "primary"
          },
          {
            "id": "discussion-boards-event-2",
            "recordId": "discussion-boards-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Reply posted - Follow-up",
            "description": "A new field checklist suggestion was added. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "discussion-boards-event-3",
            "recordId": "discussion-boards-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Reply posted - West region",
            "description": "A new field checklist suggestion was added. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "discussion-boards-event-4",
            "recordId": "discussion-boards-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Reply posted - Customer response",
            "description": "A new field checklist suggestion was added. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "discussion-boards-event-5",
            "recordId": "discussion-boards-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Reply posted - Regional operations review with a deliberately long title",
            "description": "A new field checklist suggestion was added. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "discussion-boards-event-6",
            "recordId": "discussion-boards-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Reply posted - Completed preview",
            "description": "A new field checklist suggestion was added. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface DiscussionBoardsPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface DiscussionBoardsPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: DiscussionBoardsPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function DiscussionBoardsPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: DiscussionBoardsPresentationProps) {
  if (error) return <p role="alert">The Discussion Boards presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Discussion Boards presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Discussion Boards</p>
        <h1>Discussion overview</h1>
        <p>Boards, topics, participation, unanswered work, and recent posts.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/discussion-boards`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "discussion-boards-live",
      "_type": "module.discussion-boards",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Choose Chat Rooms for fast conversation and Discussion Boards for durable topics. Avoid enabling both for the same job without a clear information lifecycle.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/discussion-boards.html).

---
title: "Mail reader"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/mail-reader.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Mail reader

Provides a read-focused view across authorized personal/shared mail accounts with search, unread filtering, plain-text message detail, read state, relations, activity, dynamic fields, and favorites.

## In brief

- **Runtime key:** module.mail-reader
- **Experience:** Secured inbound mail
- **Security:** Server-enforced

Use Mail Reader when tenant users need a bounded view of synchronized email inside the app without exposing mail-server settings, credentials, or raw executable content.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.mail-reader. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Provides a read-focused view across authorized personal/shared mail accounts with search, unread filtering, plain-text message detail, read state, relations, activity, dynamic fields, and favorites.

## Key capabilities

- Select authorized personal or shared accounts and view unread counts.
- Search messages and filter unread mail.
- Read safe plain-text headers, previews, and bodies; raw HTML is not rendered.
- Mark permitted messages read/unread and connect them to favorites, relations, activity, and custom fields.

## Common uses

- Shared operations or support mailbox review.
- Account/project email research linked to business records.
- Read-focused compliance or case correspondence views.

## How it connects

Mail Reader represents synchronized mail records. Use Conversations when messages should become managed customer threads and Universal Inbox when a message requires assignment or action.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Account ownership/shared access, SaaS, tenant, DataRole, and location are enforced server-side. Incoming-server settings, credential references, raw HTML, and private provider details are excluded from browser responses.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.mail-reader` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

## Copy/paste the complete Mail Reader experience

The native block is the quickest complete page: authorized accounts, unread counts, server-side search, message detail, safe plain text, read state, custom fields, relation/activity counts, and favorites.

```
{
  "blocks": [
    { "_id": "inbound-mail", "_type": "module.mail-reader", "props": {}, "children": [] }
  ]
}
```

### Custom unstyled React account, list, and message view

This component requests one bounded server page at a time. The account and location values narrow an already-authorized result; they never establish tenant or mailbox authority.

```
import { FormEvent, useEffect, useState } from "react";
import type { MailReaderList, MailReaderMessageDetail } from "@buildwithhq/module-sdk";
import { getMailReaderMessage, listMailReaderMessages } from "./api";

const empty: MailReaderList = { contractVersion: 1, pageNumber: 1, pageSize: 50, totalRecords: 0, totalPages: 0, accounts: [], items: [] };

export function UnstyledMailReader({ locationId = "" }) {
  const [draft, setDraft] = useState("");
  const [search, setSearch] = useState("");
  const [mailAccountId, setMailAccountId] = useState("");
  const [unreadOnly, setUnreadOnly] = useState(false);
  const [page, setPage] = useState(1);
  const [result, setResult] = useState<MailReaderList>(empty);
  const [selected, setSelected] = useState<MailReaderMessageDetail | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const controller = new AbortController();
    setError(null);
    listMailReaderMessages(mailAccountId, search, unreadOnly, controller.signal, locationId, page, 50)
      .then(setResult)
      .catch((caught: unknown) => { if (!controller.signal.aborted) setError(caught instanceof Error ? caught.message : "Mail could not be loaded."); });
    return () => controller.abort();
  }, [locationId, mailAccountId, page, search, unreadOnly]);

  function submit(event: FormEvent) { event.preventDefault(); setPage(1); setSearch(draft.trim()); }
  async function open(recordId: string) { setSelected(await getMailReaderMessage(recordId)); }

  return <section className="custom-mail-reader">
    <h1>Mail reader</h1>
    <form role="search" onSubmit={submit}>
      <label>Account<select value={mailAccountId} onChange={event => { setMailAccountId(event.target.value); setPage(1); }}><option value="">All authorized accounts</option>{result.accounts.map(account => <option key={account.mailAccountId} value={account.mailAccountId}>{account.accountName} ({account.unreadCount} unread)</option>)}</select></label>
      <label>Search<input value={draft} maxLength={200} onChange={event => setDraft(event.target.value)} /></label>
      <label><input type="checkbox" checked={unreadOnly} onChange={event => { setUnreadOnly(event.target.checked); setPage(1); }} /> Unread only</label>
      <button>Search</button>
    </form>
    {error && <p role="alert">{error}</p>}
    <div className="mail-columns">
      <ol>{result.items.map(message => <li key={message.recordId}><button type="button" onClick={() => void open(message.recordId)}><strong>{message.subject || "(No subject)"}</strong><span>{message.fromAddress || "Unknown sender"}</span><small>{message.previewText || "No plain-text preview"}{message.isRead ? "" : " - Unread"}</small></button></li>)}</ol>
      <article>{selected ? <><h2>{selected.subject || "(No subject)"}</h2><dl><dt>From</dt><dd>{selected.fromAddress || "-"}</dd><dt>To</dt><dd>{selected.toAddress || "-"}</dd><dt>Received</dt><dd>{selected.receivedUtc ? new Date(selected.receivedUtc).toLocaleString() : "-"}</dd></dl><p className="mail-body">{selected.bodyText || "No plain-text body is available."}</p>{selected.hasHtmlBody && <small>HTML content is intentionally not rendered.</small>}<p>{selected.relationCount} related - {selected.activityCount} activity</p></> : <p>Select a message.</p>}</article>
    </div>
    <nav aria-label="Mail pages"><button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button><span>Page {result.pageNumber} of {Math.max(1, result.totalPages)}</span><button disabled={page >= result.totalPages} onClick={() => setPage(value => value + 1)}>Next</button></nav>
  </section>;
}
```

### Read and favorite actions

Read state is allowed only when `canMarkRead` is true. Mail Reader does not invent send or reply endpoints: use Conversations for managed replies and Universal Inbox for assigned work.

```
import type { MailReaderMessageDetail } from "@buildwithhq/module-sdk";
import { getMailReaderMessage, setMailReaderFavorite, setMailReaderRead } from "./api";

export async function toggleRead(message: MailReaderMessageDetail) {
  if (!message.canMarkRead) throw new Error("This message's read state cannot be changed.");
  await setMailReaderRead(message.recordId, !message.isRead, message.updatedUtc);
  return getMailReaderMessage(message.recordId);
}

export async function toggleMailFavorite(message: MailReaderMessageDetail) {
  await setMailReaderFavorite(message.recordId, !message.isFavorite);
  return getMailReaderMessage(message.recordId);
}
```

### Optional starter styling

```
.custom-mail-reader { width: 100%; max-width: none; }
.custom-mail-reader form, .custom-mail-reader nav { align-items: end; display: flex; flex-wrap: wrap; gap: .75rem; }
.mail-columns { display: grid; gap: 1rem; grid-template-columns: minmax(260px, 36%) minmax(0, 1fr); margin: 1rem 0; }
.mail-columns ol { list-style: none; margin: 0; padding: 0; }
.mail-columns li button { background: transparent; border: 0; display: grid; gap: .2rem; padding: .75rem; text-align: left; width: 100%; }
.mail-columns article { border: 1px solid var(--line, #d8dee8); padding: 1rem; }
.mail-body { white-space: pre-wrap; }
@media (max-width: 760px) { .mail-columns { grid-template-columns: 1fr; } }
```

### Exact data path

| Purpose | Route | Procedure |
| --- | --- | --- |
| Accounts and messages | `GET /api/modules/mail-reader` | `sp_MailReader_ListSecured` |
| Safe detail | `GET /api/modules/mail-reader/{recordId}` | `sp_MailReader_GetSecured` |
| Read state | `PUT /api/modules/mail-reader/{recordId}/read` | `sp_MailReader_SetReadSecured` |
| Favorite | `PUT /api/modules/mail-reader/{recordId}/favorite` | `sp_MailReader_SetFavoriteSecured` |

The list is capped at 200 rows per request and detail returns `bodyText`, not executable message HTML, provider credentials, mailbox connection settings, or storage coordinates.

## Build a professional Mail reader dashboard

These six registry-backed presentation blocks let a designer turn the secured Mail reader API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/mail-reader`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/mail-reader-sample.json`, its executable authenticated page at `pages/first-class/mail-reader-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Mail reader projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Unread, received, account, attachment, and relation counts |
| `entity-list` | `core.entity-list` | Recent mail from accounts the user may read |
| `progress-list` | `core.progress-list` | Distribution by account, read state, or folder |
| `series-chart` | `core.series-chart` | Received, read, linked, and favorited mail |
| `data-grid` | `core.presentation-grid` | One bounded page without raw HTML or credentials |
| `timeline` | `core.timeline` | Receive, read, favorite, relate, attach, and retention events |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "mail-reader-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Mail overview",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "unread",
            "label": "Unread",
            "value": 37,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "today",
            "label": "Received today",
            "value": 92,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "accounts",
            "label": "Accessible accounts",
            "value": 4,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "linked",
            "label": "Linked to records",
            "value": 21,
            "format": "number",
            "tone": "success"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "mail-reader-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Recent mail",
        "hasMore": true,
        "items": [
          {
            "id": "mail-reader-sample-1",
            "recordId": "mail-reader-record-1",
            "primary": "Updated project schedule",
            "secondary": "maya@example.test - Operations inbox",
            "status": {
              "key": "unread",
              "label": "Unread",
              "tone": "warning"
            },
            "trailing": "2 attachments"
          },
          {
            "id": "mail-reader-sample-2",
            "recordId": "mail-reader-record-2",
            "primary": "Updated project schedule - Follow-up",
            "secondary": "maya@example.test - Operations inbox - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "mail-reader-sample-3",
            "recordId": "mail-reader-record-3",
            "primary": "Updated project schedule - West region",
            "secondary": "maya@example.test - Operations inbox - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "mail-reader-sample-4",
            "recordId": "mail-reader-record-4",
            "primary": "Updated project schedule - Customer response",
            "secondary": "maya@example.test - Operations inbox - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "mail-reader-sample-5",
            "recordId": "mail-reader-record-5",
            "primary": "Updated project schedule - Regional operations review with a deliberately long title",
            "secondary": "maya@example.test - Operations inbox - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "mail-reader-sample-6",
            "recordId": "mail-reader-record-6",
            "primary": "Updated project schedule - Completed preview",
            "secondary": "maya@example.test - Operations inbox - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "mail-reader-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Mail by account",
        "items": [
          {
            "key": "operations",
            "label": "Operations",
            "value": 48,
            "maximum": 92,
            "displayValue": "48",
            "tone": "primary",
            "status": {
              "key": "operations",
              "label": "Operations",
              "tone": "primary"
            }
          },
          {
            "key": "support",
            "label": "Support",
            "value": 31,
            "maximum": 92,
            "displayValue": "31",
            "tone": "warning",
            "status": {
              "key": "support",
              "label": "Support",
              "tone": "warning"
            }
          },
          {
            "key": "sales",
            "label": "Sales",
            "value": 13,
            "maximum": 92,
            "displayValue": "13",
            "tone": "success",
            "status": {
              "key": "sales",
              "label": "Sales",
              "tone": "success"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "mail-reader-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Mail volume",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Received",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Read",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "mail-reader-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Authorized messages",
        "columns": [
          {
            "key": "subject",
            "label": "Subject",
            "type": "text",
            "align": "left"
          },
          {
            "key": "from",
            "label": "From",
            "type": "text",
            "align": "left"
          },
          {
            "key": "account",
            "label": "Account",
            "type": "text",
            "align": "left"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "received",
            "label": "Received",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "mail-reader-row-1",
            "recordId": "mail-reader-record-1",
            "cells": {
              "subject": "Updated project schedule",
              "from": "maya@example.test",
              "account": "Operations",
              "status": {
                "key": "unread",
                "label": "Unread",
                "tone": "warning"
              },
              "received": "2026-09-04T17:19:00Z"
            }
          },
          {
            "id": "mail-reader-row-2",
            "recordId": "mail-reader-record-2",
            "cells": {
              "subject": "Updated project schedule - Follow-up",
              "from": "maya@example.test",
              "account": "Operations",
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "received": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "mail-reader-row-3",
            "recordId": "mail-reader-record-3",
            "cells": {
              "subject": "Updated project schedule - West region",
              "from": "maya@example.test",
              "account": "Operations",
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "received": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "mail-reader-row-4",
            "recordId": "mail-reader-record-4",
            "cells": {
              "subject": "Updated project schedule - Customer response",
              "from": "maya@example.test",
              "account": "Operations",
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "received": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "mail-reader-row-5",
            "recordId": "mail-reader-record-5",
            "cells": {
              "subject": "Updated project schedule - Regional operations review with a deliberately long title",
              "from": "maya@example.test - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "account": "Operations",
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "received": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "mail-reader-row-6",
            "recordId": "mail-reader-record-6",
            "cells": {
              "subject": "Updated project schedule - Completed preview",
              "from": "maya@example.test",
              "account": "Operations",
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "received": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 37,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "mail-reader-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Mail activity",
        "hasMore": true,
        "items": [
          {
            "id": "mail-reader-event-1",
            "recordId": "mail-reader-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Message linked",
            "description": "Updated project schedule was related to Project North.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "mail-reader-event-2",
            "recordId": "mail-reader-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Message linked - Follow-up",
            "description": "Updated project schedule was related to Project North. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "mail-reader-event-3",
            "recordId": "mail-reader-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Message linked - West region",
            "description": "Updated project schedule was related to Project North. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "mail-reader-event-4",
            "recordId": "mail-reader-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Message linked - Customer response",
            "description": "Updated project schedule was related to Project North. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "mail-reader-event-5",
            "recordId": "mail-reader-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Message linked - Regional operations review with a deliberately long title",
            "description": "Updated project schedule was related to Project North. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "mail-reader-event-6",
            "recordId": "mail-reader-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Message linked - Completed preview",
            "description": "Updated project schedule was related to Project North. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface MailReaderPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface MailReaderPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: MailReaderPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function MailReaderPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: MailReaderPresentationProps) {
  if (error) return <p role="alert">The Mail reader presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Mail reader presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Mail reader</p>
        <h1>Mail overview</h1>
        <p>Authorized accounts, unread messages, senders, links to work, and recent mail activity.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/mail-reader`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "mail-reader-live",
      "_type": "module.mail-reader",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Do not treat Mail Reader as an unrestricted webmail client. Define the synchronized accounts, read-state authority, and handoff into Conversations or Inbox explicitly.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/mail-reader.html).

---
title: "Favorites"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/favorites.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Favorites

Gives each user a secured cross-module list of saved records with search, module filters, pinning, change tracking, related context, activity, and dynamic fields.

## In brief

- **Runtime key:** module.favorites
- **Experience:** Personal workspace
- **Security:** Server-enforced

Use Favorites as a personal shortcut layer so each user can return to important records across the app without changing the records themselves.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.favorites. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Gives each user a secured cross-module list of saved records with search, module filters, pinning, change tracking, related context, activity, and dynamic fields.

## Key capabilities

- Search personal favorites and filter by source module.
- Pin, reorder, remove, and optionally track changes on saved records.
- Show current secured status, location, relations, activity, and dynamic fields.
- Collapse duplicate favorite targets into a coherent personal workspace.

## Common uses

- Pinned customers, projects, cases, files, or articles.
- A personal watch list for records whose changes matter.
- Cross-module navigation for frequently used work.

## How it connects

Any supported canonical Record can participate. The favorite stores personal preference; the target remains owned by its native module and is reauthorized whenever it is listed or opened.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Only the current user's favorite rows are returned. Target records, related records, fields, activity, and location are independently secured, so a favorite never preserves access after permission is removed.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.favorites` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

## Copy/paste the complete Favorites workspace

The native block provides personal search, module and tracked filters, detail, related context, pinning, ordering, change tracking, dynamic fields, and removal.

```
{
  "blocks": [
    { "_id": "my-favorites", "_type": "module.favorites", "props": {}, "children": [] }
  ]
}
```

### Custom unstyled React list and detail

Each result page is assembled by the secured procedure. Do not cache a favorite as proof that its target is still visible; opening and listing reauthorize the target every time.

```
import { FormEvent, useEffect, useState } from "react";
import { favoriteDynamicValue, type FavoriteDetail, type FavoritesList } from "@buildwithhq/module-sdk";
import { getFavorite, listFavorites } from "./api";

const empty: FavoritesList = { contractVersion: 1, pageNumber: 1, pageSize: 50, totalRecords: 0, totalPages: 0, modules: [], items: [] };

export function UnstyledFavorites({ locationId = "" }) {
  const [draft, setDraft] = useState("");
  const [search, setSearch] = useState("");
  const [moduleKey, setModuleKey] = useState("");
  const [trackedOnly, setTrackedOnly] = useState(false);
  const [page, setPage] = useState(1);
  const [result, setResult] = useState<FavoritesList>(empty);
  const [selected, setSelected] = useState<FavoriteDetail | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const controller = new AbortController();
    listFavorites(moduleKey, search, trackedOnly, controller.signal, locationId, page, 50)
      .then(setResult)
      .catch((caught: unknown) => { if (!controller.signal.aborted) setError(caught instanceof Error ? caught.message : "Favorites could not be loaded."); });
    return () => controller.abort();
  }, [locationId, moduleKey, page, search, trackedOnly]);

  function submit(event: FormEvent) { event.preventDefault(); setPage(1); setSearch(draft.trim()); }
  async function open(recordId: string) { setSelected(await getFavorite(recordId)); }

  return <section className="custom-favorites">
    <h1>Favorites</h1>
    <form role="search" onSubmit={submit}>
      <label>Search<input value={draft} maxLength={200} onChange={event => setDraft(event.target.value)} /></label>
      <label>Module<select value={moduleKey} onChange={event => { setModuleKey(event.target.value); setPage(1); }}><option value="">All modules</option>{result.modules.map(module => <option key={module.moduleKey} value={module.moduleKey}>{module.moduleName}</option>)}</select></label>
      <label><input type="checkbox" checked={trackedOnly} onChange={event => { setTrackedOnly(event.target.checked); setPage(1); }} /> Tracked only</label><button>Search</button>
    </form>
    {error && <p role="alert">{error}</p>}
    <div className="favorite-columns">
      <ol>{result.items.map(item => <li key={item.recordId}><button type="button" onClick={() => void open(item.recordId)}><strong>{item.recordTitle || item.favoriteName}</strong><span>{item.moduleName} - {item.locationName || "All locations"}</span><small>{item.isPinned ? "Pinned" : "Saved"}{item.trackChanges ? " - Tracking changes" : ""}</small></button></li>)}</ol>
      <article>{selected ? <><h2>{selected.recordTitle || selected.favoriteName}</h2><p>{selected.recordStatus || "No status"} - {selected.relationCount} related - {selected.activityCount} activity</p><ul>{selected.relatedRecords.map(related => <li key={related.recordRelationId}>{related.title || "Untitled"} ({related.moduleName})</li>)}</ul><dl>{selected.dynamicFields.map(field => <div key={field.fieldKey}><dt>{field.fieldLabel}</dt><dd>{favoriteDynamicValue(field)}</dd></div>)}</dl></> : <p>Select a favorite.</p>}</article>
    </div>
    <nav aria-label="Favorite pages"><button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button><span>Page {result.pageNumber} of {Math.max(1, result.totalPages)}</span><button disabled={page >= result.totalPages} onClick={() => setPage(value => value + 1)}>Next</button></nav>
  </section>;
}
```

### Pin, track, order, and remove

Preference updates address the canonical `recordId` and operate only on the current user's favorite. Other modules add a record with their own favorite endpoint; this workspace manages the resulting personal row.

```
import type { FavoriteDetail } from "@buildwithhq/module-sdk";
import { getFavorite, setFavorite, updateFavoritePreferences } from "./api";

export async function updateFavorite(current: FavoriteDetail, change: Partial<{ isPinned: boolean; trackChanges: boolean; sortOrder: number }>) {
  await updateFavoritePreferences(current.recordId, {
    isPinned: change.isPinned ?? current.isPinned,
    trackChanges: change.trackChanges ?? current.trackChanges,
    sortOrder: change.sortOrder ?? current.sortOrder,
  });
  return getFavorite(current.recordId);
}

export const pinFavorite = (current: FavoriteDetail) => updateFavorite(current, { isPinned: true });
export const trackFavorite = (current: FavoriteDetail) => updateFavorite(current, { trackChanges: true });
export async function removeFavorite(recordId: string) { return setFavorite(recordId, false); }
```

### Optional starter styling

```
.custom-favorites { width: 100%; max-width: none; }
.custom-favorites form, .custom-favorites nav { align-items: end; display: flex; flex-wrap: wrap; gap: .75rem; }
.favorite-columns { display: grid; gap: 1rem; grid-template-columns: minmax(260px, 35%) minmax(0, 1fr); margin: 1rem 0; }
.favorite-columns ol { list-style: none; margin: 0; padding: 0; }
.favorite-columns li button { background: transparent; border: 0; display: grid; gap: .2rem; padding: .75rem; text-align: left; width: 100%; }
.favorite-columns article { border: 1px solid var(--line, #d8dee8); padding: 1rem; }
@media (max-width: 760px) { .favorite-columns { grid-template-columns: 1fr; } }
```

### Exact data path

| Purpose | Route | Procedure |
| --- | --- | --- |
| Personal list | `GET /api/modules/favorites` | `sp_Favorites_ListSecured` |
| Secured target detail | `GET /api/modules/favorites/{recordId}` | `sp_Favorites_GetSecured` |
| Current user's state | `GET /api/modules/favorites/{recordId}/state` | `sp_Favorites_GetStateSecured` |
| Add/remove | `PUT /api/modules/favorites/{recordId}/favorite` | `sp_Favorites_SetSecured` |
| Personal preferences | `PUT /api/modules/favorites/{recordId}/preferences` | `sp_Favorites_UpdateSecured` |

Record surfaces use the shared 25-by-25-pixel five-point star, gray when the record is not saved and gold when it is a favorite. If a record projection does not already include `isFavorite`, the shared component resolves it through the secured state route; successful changes synchronize every rendered copy of that record.

Lists are capped at 200 favorites per request. A favorite is navigation and personal preference, never an access grant, assignment, approval, or durable work queue.

## Build a professional Favorites dashboard

These six registry-backed presentation blocks let a designer turn the secured Favorites API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/favorites`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/favorites-sample.json`, its executable authenticated page at `pages/first-class/favorites-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Favorites projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Favorite total, module mix, and recently changed items |
| `entity-list` | `core.entity-list` | Saved records that remain authorized now |
| `progress-list` | `core.progress-list` | Distribution by owning module or state |
| `series-chart` | `core.series-chart` | Adds, removals, and changes over time |
| `data-grid` | `core.presentation-grid` | One bounded cross-module favorite page |
| `timeline` | `core.timeline` | Add, remove, source update, permission loss, and restoration |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "favorites-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Favorite records",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "total",
            "label": "Your favorites",
            "value": 57,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "contacts",
            "label": "Contacts",
            "value": 19,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "files",
            "label": "Files",
            "value": 11,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "changed",
            "label": "Changed this week",
            "value": 8,
            "format": "number",
            "tone": "warning"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "favorites-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Recently changed favorites",
        "hasMore": true,
        "items": [
          {
            "id": "favorites-sample-1",
            "recordId": "favorites-record-1",
            "primary": "Maya Chen",
            "secondary": "Contact - Acme Field Services",
            "status": {
              "key": "updated",
              "label": "Updated",
              "tone": "primary"
            },
            "trailing": "Reno"
          },
          {
            "id": "favorites-sample-2",
            "recordId": "favorites-record-2",
            "primary": "Maya Chen - Follow-up",
            "secondary": "Contact - Acme Field Services - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "favorites-sample-3",
            "recordId": "favorites-record-3",
            "primary": "Maya Chen - West region",
            "secondary": "Contact - Acme Field Services - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "favorites-sample-4",
            "recordId": "favorites-record-4",
            "primary": "Maya Chen - Customer response",
            "secondary": "Contact - Acme Field Services - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "favorites-sample-5",
            "recordId": "favorites-record-5",
            "primary": "Maya Chen - Regional operations review with a deliberately long title",
            "secondary": "Contact - Acme Field Services - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "favorites-sample-6",
            "recordId": "favorites-record-6",
            "primary": "Maya Chen - Completed preview",
            "secondary": "Contact - Acme Field Services - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "favorites-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Favorites by module",
        "items": [
          {
            "key": "contacts",
            "label": "Contacts",
            "value": 19,
            "maximum": 45,
            "displayValue": "19",
            "tone": "primary",
            "status": {
              "key": "contacts",
              "label": "Contacts",
              "tone": "primary"
            }
          },
          {
            "key": "work",
            "label": "Work orders",
            "value": 15,
            "maximum": 45,
            "displayValue": "15",
            "tone": "warning",
            "status": {
              "key": "work",
              "label": "Work orders",
              "tone": "warning"
            }
          },
          {
            "key": "files",
            "label": "Files",
            "value": 11,
            "maximum": 45,
            "displayValue": "11",
            "tone": "success",
            "status": {
              "key": "files",
              "label": "Files",
              "tone": "success"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "favorites-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Favorite activity",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Added",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Removed",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "favorites-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Your visible favorites",
        "columns": [
          {
            "key": "record",
            "label": "Record",
            "type": "text",
            "align": "left"
          },
          {
            "key": "module",
            "label": "Module",
            "type": "text",
            "align": "left"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "location",
            "label": "Location",
            "type": "text",
            "align": "left"
          },
          {
            "key": "updated",
            "label": "Updated",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "favorites-row-1",
            "recordId": "favorites-record-1",
            "cells": {
              "record": "Maya Chen",
              "module": "Contacts",
              "status": {
                "key": "updated",
                "label": "Updated",
                "tone": "primary"
              },
              "location": "Reno",
              "updated": "2026-09-04T12:36:00Z"
            }
          },
          {
            "id": "favorites-row-2",
            "recordId": "favorites-record-2",
            "cells": {
              "record": "Maya Chen - Follow-up",
              "module": "Contacts",
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "location": "Reno",
              "updated": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "favorites-row-3",
            "recordId": "favorites-record-3",
            "cells": {
              "record": "Maya Chen - West region",
              "module": "Contacts",
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "location": "Reno",
              "updated": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "favorites-row-4",
            "recordId": "favorites-record-4",
            "cells": {
              "record": "Maya Chen - Customer response",
              "module": "Contacts",
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "location": "Reno",
              "updated": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "favorites-row-5",
            "recordId": "favorites-record-5",
            "cells": {
              "record": "Maya Chen - Regional operations review with a deliberately long title",
              "module": "Contacts - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "location": "Reno",
              "updated": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "favorites-row-6",
            "recordId": "favorites-record-6",
            "cells": {
              "record": "Maya Chen - Completed preview",
              "module": "Contacts",
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "location": "Reno",
              "updated": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 57,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "favorites-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Favorite activity",
        "hasMore": true,
        "items": [
          {
            "id": "favorites-event-1",
            "recordId": "favorites-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Favorite added",
            "description": "North Wing closeout was added to your favorites.",
            "actor": "You",
            "tone": "success"
          },
          {
            "id": "favorites-event-2",
            "recordId": "favorites-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Favorite added - Follow-up",
            "description": "North Wing closeout was added to your favorites. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "favorites-event-3",
            "recordId": "favorites-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Favorite added - West region",
            "description": "North Wing closeout was added to your favorites. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "favorites-event-4",
            "recordId": "favorites-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Favorite added - Customer response",
            "description": "North Wing closeout was added to your favorites. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "favorites-event-5",
            "recordId": "favorites-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Favorite added - Regional operations review with a deliberately long title",
            "description": "North Wing closeout was added to your favorites. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "favorites-event-6",
            "recordId": "favorites-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Favorite added - Completed preview",
            "description": "North Wing closeout was added to your favorites. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface FavoritesPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface FavoritesPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: FavoritesPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function FavoritesPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: FavoritesPresentationProps) {
  if (error) return <p role="alert">The Favorites presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Favorites presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Favorites</p>
        <h1>Favorite records</h1>
        <p>The current user's saved records, module mix, recent changes, and fast navigation.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/favorites`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "favorites-live",
      "_type": "module.favorites",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Favorites complement, but do not replace, queues or assignments. Use a workflow/Inbox item when work must be completed by a deadline or owner.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/favorites.html).

---
title: "Notifications"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/notifications.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Notifications

Provides recipient-scoped alerts with unread filtering, detail, dismissal, source-record context, relations, activity, and source favorites.

## In brief

- **Runtime key:** module.notifications
- **Experience:** Personal alerts
- **Security:** Server-enforced

Use Notifications for personal awareness of events, assignments, changes, and workflow outcomes that do not require the richer ownership lifecycle of Universal Inbox.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.notifications. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Provides recipient-scoped alerts with unread filtering, detail, dismissal, source-record context, relations, activity, and source favorites.

## Key capabilities

- Search current-recipient notifications and filter unread items.
- Open bounded detail and mark or dismiss notification state.
- Show a permitted source title, location, relations, and activity.
- Favorite an authorized source record directly from the notification.

## Common uses

- Assignment, mention, publication, and status-change alerts.
- Workflow completion, failure, or approval attention.
- Personal reminders that link back to the canonical source record.

## How it connects

Notifications point to native source records across modules. Use Universal Inbox for shared triage, ownership, SLA, and AI action preparation; use Notifications for recipient-scoped awareness.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Only rows for the current recipient and app/account are returned. Linked source metadata appears only after its normal DataRole and location checks; the browser cannot submit recipient or permission authority.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.notifications` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

## Build a professional Notifications dashboard

These six registry-backed presentation blocks let a designer turn the secured Notifications API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/notifications`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/notifications-sample.json`, its executable authenticated page at `pages/first-class/notifications-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Notifications projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Unread, action-needed, received, read, and priority counts |
| `entity-list` | `core.entity-list` | Newest notifications whose source is still visible |
| `progress-list` | `core.progress-list` | Distribution by source, priority, or state |
| `series-chart` | `core.series-chart` | Received, read, dismissed, and actioned events |
| `data-grid` | `core.presentation-grid` | One bounded personal notification page |
| `timeline` | `core.timeline` | Creation, delivery, read, dismiss, source action, and expiry |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "notifications-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Notification center",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "unread",
            "label": "Unread",
            "value": 24,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "action",
            "label": "Action needed",
            "value": 6,
            "format": "number",
            "tone": "danger"
          },
          {
            "key": "today",
            "label": "Received today",
            "value": 41,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "read",
            "label": "Read today",
            "value": 29,
            "format": "number",
            "tone": "success"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "notifications-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Recent notifications",
        "hasMore": true,
        "items": [
          {
            "id": "notifications-sample-1",
            "recordId": "notifications-record-1",
            "primary": "Checklist awaiting signoff",
            "secondary": "North Wing closeout - Work Orders",
            "status": {
              "key": "action-needed",
              "label": "Action needed",
              "tone": "warning"
            },
            "trailing": "5 min ago"
          },
          {
            "id": "notifications-sample-2",
            "recordId": "notifications-record-2",
            "primary": "Checklist awaiting signoff - Follow-up",
            "secondary": "North Wing closeout - Work Orders - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "notifications-sample-3",
            "recordId": "notifications-record-3",
            "primary": "Checklist awaiting signoff - West region",
            "secondary": "North Wing closeout - Work Orders - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "notifications-sample-4",
            "recordId": "notifications-record-4",
            "primary": "Checklist awaiting signoff - Customer response",
            "secondary": "North Wing closeout - Work Orders - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "notifications-sample-5",
            "recordId": "notifications-record-5",
            "primary": "Checklist awaiting signoff - Regional operations review with a deliberately long title",
            "secondary": "North Wing closeout - Work Orders - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "notifications-sample-6",
            "recordId": "notifications-record-6",
            "primary": "Checklist awaiting signoff - Completed preview",
            "secondary": "North Wing closeout - Work Orders - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "notifications-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Notifications by source",
        "items": [
          {
            "key": "work",
            "label": "Work Orders",
            "value": 11,
            "maximum": 24,
            "displayValue": "11",
            "tone": "primary",
            "status": {
              "key": "work",
              "label": "Work Orders",
              "tone": "primary"
            }
          },
          {
            "key": "checklists",
            "label": "Checklists",
            "value": 8,
            "maximum": 24,
            "displayValue": "8",
            "tone": "warning",
            "status": {
              "key": "checklists",
              "label": "Checklists",
              "tone": "warning"
            }
          },
          {
            "key": "conversations",
            "label": "Conversations",
            "value": 5,
            "maximum": 24,
            "displayValue": "5",
            "tone": "success",
            "status": {
              "key": "conversations",
              "label": "Conversations",
              "tone": "success"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "notifications-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Notification activity",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Received",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Read",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "notifications-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Your notifications",
        "columns": [
          {
            "key": "notification",
            "label": "Notification",
            "type": "text",
            "align": "left"
          },
          {
            "key": "source",
            "label": "Source",
            "type": "text",
            "align": "left"
          },
          {
            "key": "priority",
            "label": "Priority",
            "type": "status",
            "align": "left"
          },
          {
            "key": "state",
            "label": "State",
            "type": "status",
            "align": "left"
          },
          {
            "key": "created",
            "label": "Created",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "notifications-row-1",
            "recordId": "notifications-record-1",
            "cells": {
              "notification": "Checklist awaiting signoff",
              "source": "Work Orders",
              "priority": {
                "key": "high",
                "label": "High",
                "tone": "danger"
              },
              "state": {
                "key": "unread",
                "label": "Unread",
                "tone": "warning"
              },
              "created": "2026-09-04T17:55:00Z"
            }
          },
          {
            "id": "notifications-row-2",
            "recordId": "notifications-record-2",
            "cells": {
              "notification": "Checklist awaiting signoff - Follow-up",
              "source": "Work Orders",
              "priority": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "state": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "created": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "notifications-row-3",
            "recordId": "notifications-record-3",
            "cells": {
              "notification": "Checklist awaiting signoff - West region",
              "source": "Work Orders",
              "priority": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "state": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "created": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "notifications-row-4",
            "recordId": "notifications-record-4",
            "cells": {
              "notification": "Checklist awaiting signoff - Customer response",
              "source": "Work Orders",
              "priority": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "state": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "created": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "notifications-row-5",
            "recordId": "notifications-record-5",
            "cells": {
              "notification": "Checklist awaiting signoff - Regional operations review with a deliberately long title",
              "source": "Work Orders - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "priority": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "state": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "created": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "notifications-row-6",
            "recordId": "notifications-record-6",
            "cells": {
              "notification": "Checklist awaiting signoff - Completed preview",
              "source": "Work Orders",
              "priority": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "state": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "created": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 24,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "notifications-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Notification activity",
        "hasMore": true,
        "items": [
          {
            "id": "notifications-event-1",
            "recordId": "notifications-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Notification read",
            "description": "Checklist awaiting signoff was marked read.",
            "actor": "You",
            "tone": "success"
          },
          {
            "id": "notifications-event-2",
            "recordId": "notifications-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Notification read - Follow-up",
            "description": "Checklist awaiting signoff was marked read. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "notifications-event-3",
            "recordId": "notifications-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Notification read - West region",
            "description": "Checklist awaiting signoff was marked read. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "notifications-event-4",
            "recordId": "notifications-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Notification read - Customer response",
            "description": "Checklist awaiting signoff was marked read. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "notifications-event-5",
            "recordId": "notifications-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Notification read - Regional operations review with a deliberately long title",
            "description": "Checklist awaiting signoff was marked read. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "notifications-event-6",
            "recordId": "notifications-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Notification read - Completed preview",
            "description": "Checklist awaiting signoff was marked read. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface NotificationsPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface NotificationsPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: NotificationsPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function NotificationsPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: NotificationsPresentationProps) {
  if (error) return <p role="alert">The Notifications presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Notifications presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Notifications</p>
        <h1>Notification center</h1>
        <p>Unread attention, priority, source modules, delivery state, and recent notification activity.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/notifications`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "notifications-live",
      "_type": "module.notifications",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Notify only when the recipient can act or benefit. High-volume events should roll up into an Inbox queue, digest, or dashboard rather than producing alert fatigue.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/notifications.html).

---
title: "Dynamic Records"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/dynamic-records.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Dynamic Records

Renders tenant-owned custom modules from their validated field schema with secured list, search, create, detail, edit, status, relations, activity, and favorites.

## In brief

- **Runtime key:** module.dynamic-records
- **Experience:** Builder-defined data
- **Security:** Server-enforced

## Model your own business data

Read [Build custom data modules](../builder-guide/dynamic-module-system.html)  for the custom-field model, RecordId, field setup, permissions and public API access.

Use Dynamic Records for the domain-specific objects that make an app unique—such as assets, inspections, applications, policies, opportunities, or inventory—without writing a new native renderer for every object type.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.dynamic-records. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Renders tenant-owned custom modules from their validated field schema with secured list, search, create, detail, edit, status, relations, activity, and favorites.

## Key capabilities

- Load only a validated tenant-owned module key supplied by the page contract.
- Render the public field schema while excluding hidden and encrypted fields.
- Search, create, inspect, edit, and change status according to existing permissions.
- Participate in relations, activity, location scope, and favorites through universal RecordId.

## Common uses

- Industry-specific business objects.
- Rapidly modeled MVP records and internal tools.
- Reusable template-defined objects that do not need a specialized native experience.

## How it connects

Dynamic records compose with all universal record features and can relate to Contacts, Calendar, Files, Conversations, Work Orders, and each other. A specialized module can later replace the generic presentation while preserving canonical record identity.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

The server accepts only tenant-owned custom module keys and refuses generic access to built-in modules. Field schema, DataRole, field, record, and location rules determine which values and controls are returned.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.dynamic-records` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

## Copy/paste a complete Dynamic Records page

Set `moduleKey` to a real tenant-owned custom module key from the builder. The native renderer loads its public schema, list, create/edit form, detail, dynamic fields, relations/activity counts, and favorite state.

```
{
  "blocks": [
    {
      "_id": "asset-register", "_type": "module.dynamic-records",
      "props": { "moduleKey": "assets" }, "children": []
    }
  ]
}
```

### Schema-driven field conversion

Save this helper as `dynamicFieldInputs.ts` beside the custom component below. It converts only field definitions returned by the validated schema. Enter a date as `YYYY-MM-DD` (encoded at UTC midnight), or a timestamp with an explicit `Z` or numeric offset. The helper sends the equivalent UTC timestamp and preserves up to seven fractional digits, so server-local time cannot reinterpret the chosen instant. Decimal input uses the current native SDK's `decimal(18,6)` converter: values travel as JSON numbers when exact, or canonical decimal strings when a number would lose digits. Use the current tenant runtime SDK source for this helper; the immutable Developer Kit describes its own published edition. The current Dynamic Records contract preserves these strings on reads and writes. The editor sends only changed fields on update. Precision already lost in a legacy JSON number cannot be recovered. Other modules require their own reviewed decimal contract. The server independently enforces field visibility, write permissions, and validation.

```
import { decimalFieldInput, integerFieldInput, type DecimalFieldValue, type DynamicModuleDetail, type DynamicModuleFieldDefinition, type DynamicModuleFieldInput } from "@buildwithhq/module-sdk";

export function dynamicRawValue(detail: DynamicModuleDetail | null, fieldKey: string) {
  const field = detail?.fields.find(value => value.fieldKey === fieldKey);
  if (!field) return "";
  if (field.dataType.toLowerCase() === "json") return field.valueJson == null ? "" : JSON.stringify(field.valueJson);
  const value = field.valueText ?? field.valueInt ?? field.valueDecimal ?? field.valueDateTime ?? field.valueBool ?? field.valueGuid ?? field.valueJson;
  return value == null ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
}

export function dynamicDecimalInput(raw: string): DecimalFieldValue {
  return decimalFieldInput(raw);
}

export function dynamicFieldInput(field: DynamicModuleFieldDefinition, raw: string): DynamicModuleFieldInput {
  const dataType = field.dataType.toLowerCase();
  if (!raw) {
    if (field.required) throw new Error(`Enter ${field.label}.`);
    return { fieldKey: field.fieldKey, clear: true };
  }
  if (["boolean", "bool"].includes(dataType)) {
    if (raw !== "true" && raw !== "false") throw new Error(`Choose Yes or No for ${field.label}.`);
    return { fieldKey: field.fieldKey, valueBool: raw === "true" };
  }
  if (["int", "integer", "bigint"].includes(dataType)) return { fieldKey: field.fieldKey, valueInt: integerFieldInput(raw) };
  if (["decimal", "number", "currency"].includes(dataType)) {
    return { fieldKey: field.fieldKey, valueDecimal: dynamicDecimalInput(raw) };
  }
  if (["datetime", "date"].includes(dataType)) {
    const timestamp = dataType === "date" && /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/.test(raw) ? `${raw}T00:00:00Z` : raw;
    const zoned = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,7})?(?:Z|[+-][0-9]{2}:[0-9]{2})$/i.test(timestamp);
    const day = timestamp.slice(0, 10);
    const calendar = new Date(`${day}T00:00:00Z`);
    if (!zoned || Number(day.slice(0, 4)) < 1 || !Number.isFinite(Date.parse(timestamp)) || !Number.isFinite(calendar.getTime()) || calendar.toISOString().slice(0, 10) !== day)
      throw new Error(`Enter a valid date or a timestamp with a timezone for ${field.label}.`);
    const instant = new Date(timestamp);
    if (instant.getUTCFullYear() < 1 || instant.getUTCFullYear() > 9999)
      throw new Error(`Enter a timestamp within the supported UTC range for ${field.label}.`);
    const fraction = timestamp.match(/([.][0-9]{1,7})(?:Z|[+-][0-9]{2}:[0-9]{2})$/i)?.[1] || "";
    // Numeric offsets contain no fractional seconds, so the entered fraction is unchanged by conversion.
    const utc = instant.toISOString().replace(/[.][0-9]{3}Z$/, `${fraction}Z`);
    return { fieldKey: field.fieldKey, valueDateTime: utc };
  }
  if (dataType === "guid") return { fieldKey: field.fieldKey, valueGuid: raw };
  if (dataType === "json") return { fieldKey: field.fieldKey, valueJson: JSON.parse(raw) };
  return { fieldKey: field.fieldKey, valueText: raw };
}
```

### Custom unstyled React create/edit workspace

This example requests schema and data separately, pages on the server, and builds controls from the schema. It illustrates create, detail, edit, and favorite behavior; use the native module for its complete removal workflow. Mount it inside the verified tenant runtime host, which must remount it when the actor, session, or persisted page context changes. The configured module key is a query target, never tenant authority; built-in or foreign module keys fail closed.

```
import { FormEvent, useEffect, useRef, useState } from "react";
import { dynamicFieldDisplayValue, type DynamicModuleDetail, type DynamicModuleList, type DynamicModuleSchema } from "@buildwithhq/module-sdk";
import { createDynamicModuleRecord, getDynamicModuleRecord, getDynamicModuleSchema, listDynamicModuleRecords, setDynamicModuleFavorite, updateDynamicModuleRecord } from "./api";
import { dynamicFieldInput, dynamicRawValue } from "./dynamicFieldInputs";
import { RecordCreateScopeSelect, RecordCurrentScopeDisplay, readRecordCreateScope } from "./RecordCreateScopeSelect";

const empty = (moduleKey: string): DynamicModuleList => ({ contractVersion: 1, moduleKey, records: [], page: 1, pageSize: 50, total: 0, totalIsExact: false, hasMore: false });

export function UnstyledDynamicRecords({ moduleKey }: { moduleKey: string }) {
  return <DynamicWorkspace key={moduleKey} moduleKey={moduleKey} />;
}

function DynamicWorkspace({ moduleKey }: { moduleKey: string }) {
  const [schema, setSchema] = useState<DynamicModuleSchema | null>(null);
  const [formSchema, setFormSchema] = useState<DynamicModuleSchema | null>(null);
  const [result, setResult] = useState<DynamicModuleList>(empty(moduleKey));
  const [selected, setSelected] = useState<DynamicModuleDetail | null>(null);
  const [search, setSearch] = useState("");
  const [statusFilter, setStatusFilter] = useState("");
  const [page, setPage] = useState(1);
  const [sort, setSort] = useState<"created_asc" | "created_desc" | "title_asc" | "title_desc">("created_desc");
  const [editing, setEditing] = useState(false);
  const [creating, setCreating] = useState(false);
  const [title, setTitle] = useState("");
  const [status, setStatus] = useState("Active");
  const [values, setValues] = useState<Record<string, string>>({});
  const [originalValues, setOriginalValues] = useState<Record<string, string>>({});
  const [error, setError] = useState<string | null>(null);
  const [saving, setSaving] = useState(false);
  const [needsReview, setNeedsReview] = useState(false);
  const pending = useRef(false);
  const active = useRef(true);
  const detailVersion = useRef(0);
  useEffect(() => { active.current = true; return () => { active.current = false; detailVersion.current += 1; }; }, []);

  async function load(signal?: AbortSignal) {
    const [nextSchema, nextList] = await Promise.all([getDynamicModuleSchema(moduleKey, signal), listDynamicModuleRecords(moduleKey, search, signal, statusFilter, page, 50, sort)]);
    if (active.current && !signal?.aborted) { setSchema(nextSchema); setResult(nextList); }
  }
  useEffect(() => { const controller = new AbortController(); setError(null); load(controller.signal).catch(() => { if (!controller.signal.aborted) setError("Records could not be loaded. Reload to try the read again."); }); return () => controller.abort(); }, [moduleKey, page, search, sort, statusFilter]);

  async function open(recordId: string) {
    if (pending.current || needsReview) return;
    const version = ++detailVersion.current;
    setSelected(null); setEditing(false); setError(null);
    try {
      const detail = await getDynamicModuleRecord(moduleKey, recordId);
      if (active.current && version === detailVersion.current) setSelected(detail);
    } catch { if (active.current && version === detailVersion.current) setError("The selected record could not be loaded."); }
  }
  function begin(detail: DynamicModuleDetail | null) {
    if (!schema || pending.current || needsReview) return;
    detailVersion.current += 1; setCreating(!detail); setEditing(true); setSelected(detail); setError(null);
    setTitle(detail?.title || ""); setStatus(detail?.status || "Active"); setFormSchema(schema);
    const initial = Object.fromEntries(schema.fields.map(field => [field.fieldKey, dynamicRawValue(detail, field.fieldKey)]));
    setValues(initial); setOriginalValues(initial);
  }
  async function save(event: FormEvent) {
    event.preventDefault(); if (!formSchema || pending.current || needsReview) return;
    const form = event.currentTarget as HTMLFormElement;
    let submitted = false;
    let validationComplete = false;
    pending.current = true; setSaving(true); setError(null);
    try {
      const fields = formSchema.fields.filter(field => creating || values[field.fieldKey] !== originalValues[field.fieldKey])
        .map(field => dynamicFieldInput(field, values[field.fieldKey] || ""));
      const chosenScope = creating ? readRecordCreateScope(new FormData(form)) : null;
      if (!creating && (!selected || !selected.updatedUtc)) throw new Error("Reload this record to obtain its current revision before saving.");
      validationComplete = true; submitted = true;
      const mutation = creating
        ? await createDynamicModuleRecord(moduleKey, { ...chosenScope!, title, fields })
        : await updateDynamicModuleRecord(moduleKey, selected!.recordId, { expectedUpdatedUtc: selected!.updatedUtc!, title, status, fields });
      // A confirmed write closes the draft before any follow-up read can fail.
      submitted = false;
      if (!active.current) return;
      setEditing(false); setCreating(false);
      const detail = await getDynamicModuleRecord(moduleKey, mutation.recordId);
      if (active.current) setSelected(detail);
      await load();
    } catch (caught: unknown) {
      if (active.current) {
        if (submitted) setNeedsReview(true);
        setError(!validationComplete ? caught instanceof Error ? caught.message : "Check the form values."
          : submitted ? "The save was not confirmed. Review the current records before trying another write."
          : "The form or refresh could not be completed. Reload the current record if needed.");
      }
    } finally { pending.current = false; if (active.current) setSaving(false); }
  }
  async function favorite() {
    if (!selected || pending.current || needsReview) return;
    pending.current = true; setSaving(true); setError(null);
    let submitted = false;
    try {
      submitted = true;
      await setDynamicModuleFavorite(moduleKey, selected.recordId, !selected.isFavorite);
      submitted = false;
      const detail = await getDynamicModuleRecord(moduleKey, selected.recordId);
      if (active.current) setSelected(detail);
    } catch {
      if (active.current) { if (submitted) setNeedsReview(true); setError("The favorite change or its refresh was not confirmed. Reload to review the current state."); }
    } finally { pending.current = false; if (active.current) setSaving(false); }
  }

  return <section className="custom-dynamic-records">
    {error && <p role="alert">{error}</p>}
    {!schema && !error && <p role="status">Loading records…</p>}
    {schema && result.records.length === 0 && <p>No records match this view.</p>}
    {needsReview && <button onClick={() => window.location.reload()}>Reload to review current records</button>}
    <fieldset disabled={saving || needsReview}>
    <header><div><small>Custom module</small><h1>{schema?.displayName || moduleKey}</h1></div>{schema?.canCreate && <button onClick={() => begin(null)}>New record</button>}</header>
    <form role="search" onSubmit={event => { event.preventDefault(); setPage(1); }}><label>Search<input value={search} maxLength={400} onChange={event => { setSearch(event.target.value); setPage(1); }} /></label><label>Status<input value={statusFilter} maxLength={50} onChange={event => { setStatusFilter(event.target.value); setPage(1); }} /></label><label>Sort<select value={sort} onChange={event => { setSort(event.target.value as typeof sort); setPage(1); }}><option value="created_desc">Newest</option><option value="created_asc">Oldest</option><option value="title_asc">Title A-Z</option><option value="title_desc">Title Z-A</option></select></label></form>
    <div className="dynamic-columns"><ol>{result.records.map(record => <li key={record.recordId}><button onClick={() => void open(record.recordId)}><strong>{record.title || "Untitled"}</strong><span>{record.status}</span></button></li>)}</ol><article>{editing && formSchema ? <form onSubmit={save}>
      <label>Title<input required maxLength={300} value={title} onChange={event => setTitle(event.target.value)} /></label>
      {creating ? <RecordCreateScopeSelect allowAll /> : selected && <RecordCurrentScopeDisplay recordId={selected.recordId} />}
      {!creating && <label>Status<input maxLength={50} value={status} onChange={event => setStatus(event.target.value)} /></label>}
      {formSchema.fields.map(field => <label key={field.fieldKey}>{field.label}
        {["boolean", "bool"].includes(field.dataType.toLowerCase()) ? <select required={field.required} value={values[field.fieldKey] || ""} onChange={event => setValues(current => ({ ...current, [field.fieldKey]: event.target.value }))}><option value="">Choose a value</option><option value="true">Yes</option><option value="false">No</option></select>
        : <input required={field.required} maxLength={field.maxLength || undefined} pattern={field.validationRegex || undefined} value={values[field.fieldKey] || ""} onChange={event => setValues(current => ({ ...current, [field.fieldKey]: event.target.value }))} />}
      </label>)}<button>Save</button><button type="button" onClick={() => setEditing(false)}>Cancel</button>
    </form> : selected ? <><h2>{selected.title || "Untitled"}</h2><p>{selected.status}</p><RecordCurrentScopeDisplay recordId={selected.recordId} /><dl>{selected.fields.map(field => <div key={field.fieldKey}><dt>{field.label}</dt><dd>{dynamicFieldDisplayValue(field)}</dd></div>)}</dl><p>{selected.relationCount} relations - {selected.activityCount} activity</p><button onClick={() => void favorite()}>{selected.isFavorite ? "Remove favorite" : "Add favorite"}</button>{selected.canEdit && <button onClick={() => begin(selected)}>Edit</button>}</> : <p>Select a record.</p>}</article></div>
    <nav aria-label="Record pages"><button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button><span>Page {result.page}</span><button disabled={!result.hasMore} onClick={() => setPage(value => value + 1)}>Next</button></nav>
    </fieldset>
  </section>;
}
```

### Location changes and the current concurrency boundary

Creation uses the secured visibility/location selector without a preselected scope. Editing shows the persisted scope. Every update passes the exact `updatedUtc` from the loaded record as `expectedUpdatedUtc`; if it is absent, reload or stop rather than inventing a revision. Location changes require an explicit authorized choice: omit both values to preserve location, pass the chosen `locationId` to replace it, or use `clearLocation: true` only for an explicitly chosen All scope when permitted. SQL rechecks scope and authority. An unconfirmed write locks this example until the user reloads and reviews current records; it never retries a mutation automatically.

```
import type { DynamicModuleDetail } from "@buildwithhq/module-sdk";
import { getDynamicModuleRecord, updateDynamicModuleRecord } from "./api";

export async function moveDynamicRecord(moduleKey: string, current: DynamicModuleDetail, chosenLocationId: string) {
  if (!current.updatedUtc) throw new Error("Reload the record before moving it.");
  await updateDynamicModuleRecord(moduleKey, current.recordId, { expectedUpdatedUtc: current.updatedUtc, locationId: chosenLocationId });
  return getDynamicModuleRecord(moduleKey, current.recordId);
}

export async function chooseAllDynamicRecordLocations(moduleKey: string, current: DynamicModuleDetail) {
  if (!current.updatedUtc) throw new Error("Reload the record before moving it.");
  await updateDynamicModuleRecord(moduleKey, current.recordId, { expectedUpdatedUtc: current.updatedUtc, clearLocation: true });
  return getDynamicModuleRecord(moduleKey, current.recordId);
}
```

### Optional starter styling

```
.custom-dynamic-records { width: 100%; max-width: none; }
.custom-dynamic-records > fieldset { border: 0; margin: 0; min-width: 0; padding: 0; }
.custom-dynamic-records > fieldset > header, .custom-dynamic-records > fieldset > form, .custom-dynamic-records > fieldset > nav { align-items: end; display: flex; flex-wrap: wrap; gap: .75rem; justify-content: space-between; }
.dynamic-columns { display: grid; gap: 1rem; grid-template-columns: minmax(240px, 32%) minmax(0, 1fr); margin: 1rem 0; }
.dynamic-columns > ol { list-style: none; margin: 0; padding: 0; }
.dynamic-columns > ol button { background: transparent; border: 0; display: grid; padding: .75rem; text-align: left; width: 100%; }
.dynamic-columns > article { border: 1px solid var(--line, #d8dee8); padding: 1rem; }
.dynamic-columns article form, .dynamic-columns article dl > div { display: grid; gap: .4rem; }
@media (max-width: 760px) { .dynamic-columns { grid-template-columns: 1fr; } }
```

### Exact data path

| Purpose | Route | Procedure |
| --- | --- | --- |
| Public field schema | `GET /api/modules/dynamic/{moduleKey}/schema` | `sp_DynamicModules_GetSchemaSecured` |
| List/detail | `GET /api/modules/dynamic/{moduleKey}` and `/{recordId}` | `sp_DynamicModules_ListSecured`, `sp_DynamicModules_GetSecured` |
| Create/update | `POST /api/modules/dynamic/{moduleKey}` and `PUT /{recordId}` | `sp_DynamicModules_CreateSecured`, `sp_DynamicModules_UpdateSecured` |
| Favorite | `PUT /api/modules/dynamic/{moduleKey}/{recordId}/favorite` | `sp_DynamicModules_SetFavoriteSecured` |

Lists are capped at 100 records and writes at 200 dynamic fields. The server accepts only an active tenant-owned custom module and excludes hidden/encrypted definitions from the browser schema.

## Build a professional Dynamic Records dashboard

These six registry-backed presentation blocks let a designer turn the secured Dynamic Records API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/dynamic`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/dynamic-records-sample.json`, its executable authenticated page at `pages/first-class/dynamic-records-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Dynamic Records projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Visible records, lifecycle counts, due work, and exceptions |
| `entity-list` | `core.entity-list` | Recently changed records from one explicit custom module |
| `progress-list` | `core.progress-list` | Distribution by status, type, owner, or location |
| `series-chart` | `core.series-chart` | Create and update volume for the selected module |
| `data-grid` | `core.presentation-grid` | One bounded page using only declared display fields |
| `timeline` | `core.timeline` | Creation, field edits, status changes, relations, favorites, and archive events |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "dynamic-records-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Custom record operations",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "visible",
            "label": "Visible assets",
            "value": 1264,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "active",
            "label": "In service",
            "value": 1108,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "review",
            "label": "Review due",
            "value": 47,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "attention",
            "label": "Need attention",
            "value": 12,
            "format": "number",
            "tone": "danger"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "dynamic-records-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Recently updated assets",
        "hasMore": true,
        "items": [
          {
            "id": "dynamic-records-sample-1",
            "recordId": "dynamic-records-record-1",
            "primary": "Compressor A-104",
            "secondary": "Asset register - Reno plant",
            "status": {
              "key": "in-service",
              "label": "In service",
              "tone": "success"
            },
            "trailing": "3 relations"
          },
          {
            "id": "dynamic-records-sample-2",
            "recordId": "dynamic-records-record-2",
            "primary": "Compressor A-104 - Follow-up",
            "secondary": "Asset register - Reno plant - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "dynamic-records-sample-3",
            "recordId": "dynamic-records-record-3",
            "primary": "Compressor A-104 - West region",
            "secondary": "Asset register - Reno plant - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "dynamic-records-sample-4",
            "recordId": "dynamic-records-record-4",
            "primary": "Compressor A-104 - Customer response",
            "secondary": "Asset register - Reno plant - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "dynamic-records-sample-5",
            "recordId": "dynamic-records-record-5",
            "primary": "Compressor A-104 - Regional operations review with a deliberately long title",
            "secondary": "Asset register - Reno plant - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "dynamic-records-sample-6",
            "recordId": "dynamic-records-record-6",
            "primary": "Compressor A-104 - Completed preview",
            "secondary": "Asset register - Reno plant - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "dynamic-records-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Assets by lifecycle",
        "items": [
          {
            "key": "service",
            "label": "In service",
            "value": 1108,
            "maximum": 1264,
            "displayValue": "1108",
            "tone": "success",
            "status": {
              "key": "service",
              "label": "In service",
              "tone": "success"
            }
          },
          {
            "key": "maintenance",
            "label": "Maintenance",
            "value": 109,
            "maximum": 1264,
            "displayValue": "109",
            "tone": "warning",
            "status": {
              "key": "maintenance",
              "label": "Maintenance",
              "tone": "warning"
            }
          },
          {
            "key": "retired",
            "label": "Retired",
            "value": 47,
            "maximum": 1264,
            "displayValue": "47",
            "tone": "neutral",
            "status": {
              "key": "retired",
              "label": "Retired",
              "tone": "neutral"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "dynamic-records-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Custom record activity",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Created",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Updated",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "dynamic-records-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Visible asset records",
        "columns": [
          {
            "key": "asset",
            "label": "Asset",
            "type": "text",
            "align": "left"
          },
          {
            "key": "category",
            "label": "Category",
            "type": "text",
            "align": "left"
          },
          {
            "key": "location",
            "label": "Location",
            "type": "text",
            "align": "left"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "updated",
            "label": "Updated",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "dynamic-records-row-1",
            "recordId": "dynamic-records-record-1",
            "cells": {
              "asset": "Compressor A-104",
              "category": "Equipment",
              "location": "Reno plant",
              "status": {
                "key": "service",
                "label": "In service",
                "tone": "success"
              },
              "updated": "2026-09-04T16:18:00Z"
            }
          },
          {
            "id": "dynamic-records-row-2",
            "recordId": "dynamic-records-record-2",
            "cells": {
              "asset": "Compressor A-104 - Follow-up",
              "category": "Equipment",
              "location": "Reno plant",
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "updated": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "dynamic-records-row-3",
            "recordId": "dynamic-records-record-3",
            "cells": {
              "asset": "Compressor A-104 - West region",
              "category": "Equipment",
              "location": "Reno plant",
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "updated": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "dynamic-records-row-4",
            "recordId": "dynamic-records-record-4",
            "cells": {
              "asset": "Compressor A-104 - Customer response",
              "category": "Equipment",
              "location": "Reno plant",
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "updated": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "dynamic-records-row-5",
            "recordId": "dynamic-records-record-5",
            "cells": {
              "asset": "Compressor A-104 - Regional operations review with a deliberately long title",
              "category": "Equipment - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "location": "Reno plant",
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "updated": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "dynamic-records-row-6",
            "recordId": "dynamic-records-record-6",
            "cells": {
              "asset": "Compressor A-104 - Completed preview",
              "category": "Equipment",
              "location": "Reno plant",
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "updated": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 1264,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "dynamic-records-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Custom record activity",
        "hasMore": true,
        "items": [
          {
            "id": "dynamic-records-event-1",
            "recordId": "dynamic-records-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Inspection date updated",
            "description": "Compressor A-104 passed its scheduled inspection.",
            "actor": "Jordan Lee",
            "tone": "success"
          },
          {
            "id": "dynamic-records-event-2",
            "recordId": "dynamic-records-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Inspection date updated - Follow-up",
            "description": "Compressor A-104 passed its scheduled inspection. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "dynamic-records-event-3",
            "recordId": "dynamic-records-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Inspection date updated - West region",
            "description": "Compressor A-104 passed its scheduled inspection. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "dynamic-records-event-4",
            "recordId": "dynamic-records-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Inspection date updated - Customer response",
            "description": "Compressor A-104 passed its scheduled inspection. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "dynamic-records-event-5",
            "recordId": "dynamic-records-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Inspection date updated - Regional operations review with a deliberately long title",
            "description": "Compressor A-104 passed its scheduled inspection. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "dynamic-records-event-6",
            "recordId": "dynamic-records-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Inspection date updated - Completed preview",
            "description": "Compressor A-104 passed its scheduled inspection. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface DynamicRecordsPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface DynamicRecordsPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: DynamicRecordsPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function DynamicRecordsPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: DynamicRecordsPresentationProps) {
  if (error) return <p role="alert">The Dynamic Records presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Dynamic Records presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Dynamic Records</p>
        <h1>Custom record operations</h1>
        <p>Builder-defined records, lifecycle state, ownership, location, relationships, and recent changes.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/dynamic`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "dynamic-records-live",
      "_type": "module.dynamic-records",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Start with Dynamic Records. Promote a domain object to a specialized first-class renderer only when its interaction model cannot be expressed well through the generic secured experience.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/dynamic-records.html).

---
title: "ActiveWorkplace"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/active-workplace.html"
reviewed_at: "2026-09-14"
authority: Official
---

# ActiveWorkplace

Pins any permitted Record into a collaborative workplace over its secured recursive relationship graph, with people, GoClaws, workflows, Record Pulse, Inbox attention, activity, and read-only Graph Playback.

## In brief

- **Runtime key:** module.active-workplace
- **Experience:** Recursive work coordination
- **Security:** Server-enforced

Use ActiveWorkplace when work crosses several connected records and people need one durable coordination view without creating a duplicate project, case, customer, file, or other business record.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.active-workplace. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Pins any permitted Record into a collaborative workplace over its secured recursive relationship graph, with people, GoClaws, workflows, Record Pulse, Inbox attention, activity, and read-only Graph Playback.

## Key capabilities

- Pin any currently permitted Record once as the workplace root.
- Capture a cycle-safe, bounded Active Graph over existing typed Record Relations.
- Coordinate named users, GoClaw assistants, and published workflows with explicit responsibilities.
- Track Active, Waiting, At Risk, Stale, Dormant, and Resolved Record Pulse states.
- Create or touch one Universal Inbox attention item when a workplace becomes At Risk or Stale.
- Record meaningful comments, participant changes, status transitions, related-record changes, and graph refreshes in an immutable activity stream.
- Reconstruct retained workplace, participant, graph, and activity state through unmistakably read-only Graph Playback while applying current permissions.
- Accept bounded builder defaults for root modules, graph depth/nodes, stale timing, participant types, GoClaw watchers, comments, and playback.

## The Active Graph

The pinned Record stays owned by its native module. ActiveWorkplace follows the existing `RecordRelations` graph to the configured depth and node limit, records identity/topology snapshots, and resolves titles, status, module, location, and edit state through the current secured Record envelope. Cycles are safe, and hidden nodes and their edges are omitted.

## Record Pulse

| Pulse | Meaning |
| --- | --- |
| **Active** | Meaningful work is moving. |
| **Waiting** | Work is intentionally waiting for a date, response, or dependency. |
| **At Risk** | The configured inactivity threshold is approaching. |
| **Stale** | The inactivity threshold has passed and attention is required. |
| **Dormant** | The workplace is intentionally inactive without being resolved. |
| **Resolved** | The coordinated work is complete. |

A bounded background evaluator observes meaningful activity and configured timing. At Risk and Stale transitions reuse Universal Inbox create-or-touch behavior, so a retry updates the existing attention item instead of creating an alert pile.

## Participants and governed assistance

A participant assignment states responsibility; it does not grant access. A user still needs current Record permission. A GoClaw must independently have AI-read access through its backing user, and material actions still require the existing action permission and approval policy. A workflow remains limited to its published definition and normal execution authority.

## Graph Playback

Playback combines temporal workplace/participant state, immutable events, retained graph snapshots, and historical Record values. It then intersects every retained Record identity with the viewer’s *current* DataRole and location scope. Historical mode has a prominent read-only banner and removes status, participant, comment, workflow, GoClaw, refresh, and destructive controls.

## Common uses

- Complex customer, case, opportunity, project, asset, incident, contract, or collections coordination.
- A Wave-like shared work surface around connected records without copying those records.
- Cross-team handoffs where responsibilities, inactivity, dependencies, and history must stay visible.
- GoClaw monitoring and workflow participation under the same permissions and approvals as the rest of the app.

## How it connects

ActiveWorkplace composes the universal Records/RecordRelations graph, tenant DataRole/location envelope, activity, workflows, GoClaw identities and actions, and Universal Inbox attention. Its state belongs to the tenant runtime database. AI Orchestration is used only when an AI job actually plans or executes work; it does not hold a shadow workplace or graph.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

The server derives app, account, user, DataRole, and locations. Root creation requires current read/edit access; each displayed graph node is reauthorized; GoClaw assignment requires independent AI-read access; and playback applies current authorization before returning any retained identity or event. Direct table access is denied to runtime and Pulse-worker roles.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Add the validated `module.active-workplace` block to an appropriate page and place that page in existing user-type menus.
2. Choose optional root module filters, graph depth (1–5), node limit (2–200), stale threshold, warning window, participant types, comments, and playback defaults.
3. If desired, select eligible default GoClaw participant IDs and retain human approval for material actions; unavailable or unauthorized agents are not assigned.
4. Confirm the app has useful typed Record Relations, then test pinning a cyclic graph, an inaccessible branch, another location, Waiting expiry, At Risk/Stale Inbox attention, and Resolved behavior.
5. Test Graph Playback after changing a user’s DataRole or location and confirm historical mode exposes no mutation controls.

## Copy/paste the complete ActiveWorkplace experience

The native block already combines root-record search and pinning, bounded graph capture, Pulse state, participants, comments, Inbox attention, graph refresh, and read-only playback. Builder props set safe defaults; the server remains authoritative.

```
{
  "blocks": [
    {
      "_id": "active-work", "_type": "module.active-workplace",
      "props": {
        "allowedRootModuleKeys": [], "maxDepth": 2, "maxNodes": 100,
        "staleAfterMinutes": 4320, "warningBeforeStaleMinutes": 720,
        "participantTypes": ["User", "GoClaw", "Workflow"],
        "defaultGoClawParticipantIds": [], "commentsEnabled": true, "playbackEnabled": true
      },
      "children": []
    }
  ]
}
```

### Custom unstyled React list, graph, people, and activity

The list is server-paged. Detail returns a cycle-safe graph snapshot capped by the workplace's reviewed depth/node policy, up to depth 5 and 200 nodes; hidden nodes and their edges are absent before React receives the response.

```
import { FormEvent, useEffect, useMemo, useState } from "react";
import { activeWorkplaceStatusLabel, type ActiveWorkplaceDetail, type ActiveWorkplaceList } from "@buildwithhq/module-sdk";
import { getActiveWorkplace, listActiveWorkplaces } from "./api";

const empty: ActiveWorkplaceList = { contractVersion: 1, pageNumber: 1, pageSize: 50, totalRecords: 0, totalPages: 0, items: [] };

export function UnstyledActiveWorkplace({ ownerUserId = "", participantId = "" }) {
  const [draft, setDraft] = useState("");
  const [search, setSearch] = useState("");
  const [status, setStatus] = useState("");
  const [page, setPage] = useState(1);
  const [result, setResult] = useState<ActiveWorkplaceList>(empty);
  const [detail, setDetail] = useState<ActiveWorkplaceDetail | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const controller = new AbortController();
    listActiveWorkplaces(search, status, page, controller.signal, 50, ownerUserId, participantId)
      .then(setResult)
      .catch((caught: unknown) => { if (!controller.signal.aborted) setError(caught instanceof Error ? caught.message : "Workplaces could not be loaded."); });
    return () => controller.abort();
  }, [ownerUserId, page, participantId, search, status]);

  const nodesByDepth = useMemo(() => {
    const grouped = new Map<number, ActiveWorkplaceDetail["graph"]["nodes"]>();
    for (const node of detail?.graph.nodes || []) { const depth = node.depth || 0; grouped.set(depth, [...(grouped.get(depth) || []), node]); }
    return [...grouped.entries()].sort(([left], [right]) => left - right);
  }, [detail]);

  function submit(event: FormEvent) { event.preventDefault(); setPage(1); setSearch(draft.trim()); }
  async function open(activeWorkplaceId: string) { setDetail(await getActiveWorkplace(activeWorkplaceId)); }

  return <section className="custom-active-workplace">
    <h1>ActiveWorkplace</h1>
    <form role="search" onSubmit={submit}><label>Find work<input value={draft} maxLength={200} onChange={event => setDraft(event.target.value)} /></label><label>Pulse<select value={status} onChange={event => { setStatus(event.target.value); setPage(1); }}><option value="">All</option>{["Active", "Waiting", "AtRisk", "Stale", "Dormant", "Resolved"].map(value => <option key={value}>{value}</option>)}</select></label><button>Search</button></form>
    {error && <p role="alert">{error}</p>}
    <div className="workplace-columns">
      <aside><ol>{result.items.map(item => <li key={item.activeWorkplaceId}><button onClick={() => void open(item.activeWorkplaceId)}><strong>{item.displayName}</strong><span>{activeWorkplaceStatusLabel(item.status)} - {item.ownerDisplayName}</span><small>{item.participantCount} people/agents - {item.pendingInboxCount} attention items</small></button></li>)}</ol></aside>
      <main>{detail ? <><header><h2>{detail.displayName}</h2><strong>{activeWorkplaceStatusLabel(detail.status)}</strong><p>{detail.rootRecord.title} ({detail.rootRecord.moduleName})</p></header><section><h3>Connected records</h3>{nodesByDepth.map(([depth, nodes]) => <div key={depth}><h4>{depth === 0 ? "Root" : `Depth ${depth}`}</h4>{nodes.map(node => <article key={node.recordId}><strong>{node.title}</strong><span>{node.moduleName} - {node.locationName || "All locations"}</span></article>)}</div>)}</section><section><h3>Participants</h3><ul>{detail.participants.map(person => <li key={person.activeWorkplaceParticipantId}>{person.displayName} - {person.participantType} - {person.responsibilityText || "Watching"}</li>)}</ul></section><section><h3>Activity</h3><ol>{detail.activity.map(item => <li key={item.activeWorkplaceEventId}><strong>{item.summary}</strong> <small>{item.actorDisplayName || item.actorType} - {new Date(item.eventAtUtc).toLocaleString()}</small></li>)}</ol></section></> : <p>Select a workplace.</p>}</main>
    </div>
    <nav aria-label="Workplace pages"><button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button><span>Page {result.pageNumber} of {Math.max(1, result.totalPages)}</span><button disabled={page >= result.totalPages} onClick={() => setPage(value => value + 1)}>Next</button></nav>
  </section>;
}
```

### Pin a record, replace settings, and move the Pulse

Create uses a visible canonical root `RecordId`. Update and Pulse changes are optimistic: always send the latest `updatedUtc` and reload after success or a 409 conflict.

```
import type { ActiveWorkplaceDetail, ActiveWorkplaceStatus } from "@buildwithhq/module-sdk";
import { createActiveWorkplace, getActiveWorkplace, setActiveWorkplaceStatus, updateActiveWorkplace } from "./api";

export async function pinRecord(rootRecordId: string) {
  const created = await createActiveWorkplace({ rootRecordId, priority: 2, graphScope: { maxDepth: 2, maxNodes: 100, playbackEnabled: true }, staleAfterMinutes: 4320, warningBeforeStaleMinutes: 720 });
  return getActiveWorkplace(created.activeWorkplaceId);
}

export async function renameWorkplace(current: ActiveWorkplaceDetail, displayName: string) {
  await updateActiveWorkplace(current.activeWorkplaceId, { displayName, ownerUserId: current.ownerUserId, priority: current.priority, graphScope: current.graphScope, staleAfterMinutes: current.staleAfterMinutes, warningBeforeStaleMinutes: current.warningBeforeStaleMinutes, expectedUpdatedUtc: current.updatedUtc });
  return getActiveWorkplace(current.activeWorkplaceId);
}

export async function changePulse(current: ActiveWorkplaceDetail, status: ActiveWorkplaceStatus, waiting?: { untilUtc?: string; reason?: string }) {
  await setActiveWorkplaceStatus(current.activeWorkplaceId, { status, waitingUntilUtc: status === "Waiting" ? waiting?.untilUtc : undefined, waitingReason: status === "Waiting" ? waiting?.reason : undefined, expectedUpdatedUtc: current.updatedUtc });
  return getActiveWorkplace(current.activeWorkplaceId);
}
```

### Participants, governed GoClaw, comments, refresh, and playback

Select participants only from the server catalog. Assignment expresses responsibility; it does not grant data access. A GoClaw remains bound to its effective user, AI-read scope, action permission, and approval policy.

```
import type { ActiveWorkplaceDetail, ActiveWorkplaceParticipantWrite } from "@buildwithhq/module-sdk";
import { addActiveWorkplaceParticipant, getActiveWorkplace, getActiveWorkplaceParticipantCatalog, getActiveWorkplacePlayback, recordActiveWorkplaceActivity, refreshActiveWorkplaceGraph, removeActiveWorkplaceParticipant } from "./api";

export const participantCatalog = (workplaceId: string) => getActiveWorkplaceParticipantCatalog(workplaceId);

export async function addParticipant(current: ActiveWorkplaceDetail, participant: ActiveWorkplaceParticipantWrite) {
  if (!current.canEdit) throw new Error("This workplace cannot be edited.");
  await addActiveWorkplaceParticipant(current.activeWorkplaceId, participant);
  return getActiveWorkplace(current.activeWorkplaceId);
}

export async function addGovernedGoClaw(current: ActiveWorkplaceDetail, participantId: string) {
  return addParticipant(current, { participantType: "GoClaw", participantId, responsibilityText: "Monitor changes and prepare suggestions", isWatcher: true, canAct: false, approvalPolicy: { materialActions: "humanApproval" } });
}

export async function removeParticipant(current: ActiveWorkplaceDetail, activeWorkplaceParticipantId: string) {
  await removeActiveWorkplaceParticipant(current.activeWorkplaceId, activeWorkplaceParticipantId);
  return getActiveWorkplace(current.activeWorkplaceId);
}

export async function postUpdate(current: ActiveWorkplaceDetail, summary: string) {
  await recordActiveWorkplaceActivity(current.activeWorkplaceId, { eventType: "Comment", summary, isMeaningfulActivity: true });
  return getActiveWorkplace(current.activeWorkplaceId);
}

export async function refreshGraph(current: ActiveWorkplaceDetail) { await refreshActiveWorkplaceGraph(current.activeWorkplaceId); return getActiveWorkplace(current.activeWorkplaceId); }
export const playBackReadOnly = (current: ActiveWorkplaceDetail, asOfUtc: string) => getActiveWorkplacePlayback(current.activeWorkplaceId, asOfUtc);
```

### Optional starter styling

```
.custom-active-workplace { width: 100%; max-width: none; }
.custom-active-workplace > form, .custom-active-workplace > nav { align-items: end; display: flex; flex-wrap: wrap; gap: .75rem; }
.workplace-columns { display: grid; gap: 1rem; grid-template-columns: 280px minmax(0, 1fr); margin: 1rem 0; }
.workplace-columns ol { list-style: none; margin: 0; padding: 0; }
.workplace-columns aside button { background: transparent; border: 0; display: grid; gap: .2rem; padding: .75rem; text-align: left; width: 100%; }
.workplace-columns main { border: 1px solid var(--line, #d8dee8); padding: 1rem; }
.workplace-columns main section article { border-left: 3px solid var(--accent, #4967d5); display: grid; margin: .5rem 0; padding: .5rem .75rem; }
@media (max-width: 760px) { .workplace-columns { grid-template-columns: 1fr; } }
```

### Exact lifecycle and data path

| Purpose | Route | Procedure |
| --- | --- | --- |
| List/detail | `GET /api/modules/active-workplace` and `/{activeWorkplaceId}` | `sp_ActiveWorkplace_ListSecured`, `sp_ActiveWorkplace_GetSecured` |
| Pin/replace/Pulse | `POST /api/modules/active-workplace`, `PATCH /{id}`, `POST /{id}/status` | `sp_ActiveWorkplace_CreateSecured`, `sp_ActiveWorkplace_UpdateSecured`, `sp_ActiveWorkplace_SetStatusSecured` |
| Participants | `GET /{id}/participants/catalog`, `POST /{id}/participants`, `DELETE /{id}/participants/{participantId}` | `sp_ActiveWorkplace_GetParticipantCatalogSecured`, `sp_ActiveWorkplace_AddParticipantSecured`, `sp_ActiveWorkplace_RemoveParticipantSecured` |
| Activity/graph | `POST /{id}/activity`, `POST /{id}/graph/refresh` | `sp_ActiveWorkplace_RecordActivitySecured`, `sp_ActiveWorkplace_RefreshGraphSecured` |
| Read-only history | `GET /{id}/playback?at=...` | `sp_ActiveWorkplace_GetPlaybackSecured` |

At Risk and Stale transitions create-or-touch Universal Inbox attention instead of duplicating alerts. Playback is explicitly `readOnly: true` and intersects retained history with the viewer's current permissions.

## Build a professional ActiveWorkplace dashboard

These six registry-backed presentation blocks let a designer turn the secured ActiveWorkplace API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/active-workplace`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/active-workplace-sample.json`, its executable authenticated page at `pages/first-class/active-workplace-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful ActiveWorkplace projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Active, healthy, at-risk, blocked, and inactive counts |
| `entity-list` | `core.entity-list` | Workspaces requiring the current participant's attention |
| `progress-list` | `core.progress-list` | Distribution by health, owner, team, or state |
| `series-chart` | `core.series-chart` | Updates, handoffs, completed work, and blockers |
| `data-grid` | `core.presentation-grid` | One bounded participant-authorized workspace page |
| `timeline` | `core.timeline` | Create, participant, relation, update, handoff, blocker, and completion |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "active-workplace-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "ActiveWorkplace operations",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "active",
            "label": "Active workspaces",
            "value": 38,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "attention",
            "label": "Need attention",
            "value": 7,
            "format": "number",
            "tone": "warning"
          },
          {
            "key": "blocked",
            "label": "Blocked",
            "value": 3,
            "format": "number",
            "tone": "danger"
          },
          {
            "key": "healthy",
            "label": "On track",
            "value": 28,
            "format": "number",
            "tone": "success"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "active-workplace-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Workspaces needing attention",
        "hasMore": true,
        "items": [
          {
            "id": "active-workplace-sample-1",
            "recordId": "active-workplace-record-1",
            "primary": "West region rollout",
            "secondary": "8 participants - 3 related records",
            "status": {
              "key": "at-risk",
              "label": "At risk",
              "tone": "warning"
            },
            "trailing": "2 blockers"
          },
          {
            "id": "active-workplace-sample-2",
            "recordId": "active-workplace-record-2",
            "primary": "West region rollout - Follow-up",
            "secondary": "8 participants - 3 related records - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "active-workplace-sample-3",
            "recordId": "active-workplace-record-3",
            "primary": "West region rollout - West region",
            "secondary": "8 participants - 3 related records - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "active-workplace-sample-4",
            "recordId": "active-workplace-record-4",
            "primary": "West region rollout - Customer response",
            "secondary": "8 participants - 3 related records - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "active-workplace-sample-5",
            "recordId": "active-workplace-record-5",
            "primary": "West region rollout - Regional operations review with a deliberately long title",
            "secondary": "8 participants - 3 related records - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "active-workplace-sample-6",
            "recordId": "active-workplace-record-6",
            "primary": "West region rollout - Completed preview",
            "secondary": "8 participants - 3 related records - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "active-workplace-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Workspace health",
        "items": [
          {
            "key": "track",
            "label": "On track",
            "value": 28,
            "maximum": 38,
            "displayValue": "28",
            "tone": "success",
            "status": {
              "key": "track",
              "label": "On track",
              "tone": "success"
            }
          },
          {
            "key": "risk",
            "label": "At risk",
            "value": 7,
            "maximum": 38,
            "displayValue": "7",
            "tone": "warning",
            "status": {
              "key": "risk",
              "label": "At risk",
              "tone": "warning"
            }
          },
          {
            "key": "blocked",
            "label": "Blocked",
            "value": 3,
            "maximum": 38,
            "displayValue": "3",
            "tone": "danger",
            "status": {
              "key": "blocked",
              "label": "Blocked",
              "tone": "danger"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "active-workplace-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Workplace activity",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Updates",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Completed items",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "active-workplace-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Active workspaces",
        "columns": [
          {
            "key": "workspace",
            "label": "Workspace",
            "type": "text",
            "align": "left"
          },
          {
            "key": "owner",
            "label": "Owner",
            "type": "text",
            "align": "left"
          },
          {
            "key": "participants",
            "label": "Participants",
            "type": "number",
            "align": "right"
          },
          {
            "key": "health",
            "label": "Health",
            "type": "status",
            "align": "left"
          },
          {
            "key": "updated",
            "label": "Updated",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "active-workplace-row-1",
            "recordId": "active-workplace-record-1",
            "cells": {
              "workspace": "West region rollout",
              "owner": "Maya Chen",
              "participants": 8,
              "health": {
                "key": "risk",
                "label": "At risk",
                "tone": "warning"
              },
              "updated": "2026-09-04T17:02:00Z"
            }
          },
          {
            "id": "active-workplace-row-2",
            "recordId": "active-workplace-record-2",
            "cells": {
              "workspace": "West region rollout - Follow-up",
              "owner": "Maya Chen",
              "participants": 9,
              "health": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "updated": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "active-workplace-row-3",
            "recordId": "active-workplace-record-3",
            "cells": {
              "workspace": "West region rollout - West region",
              "owner": "Maya Chen",
              "participants": 10,
              "health": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "updated": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "active-workplace-row-4",
            "recordId": "active-workplace-record-4",
            "cells": {
              "workspace": "West region rollout - Customer response",
              "owner": "Maya Chen",
              "participants": 11,
              "health": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "updated": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "active-workplace-row-5",
            "recordId": "active-workplace-record-5",
            "cells": {
              "workspace": "West region rollout - Regional operations review with a deliberately long title",
              "owner": "Maya Chen - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "participants": 12,
              "health": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "updated": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "active-workplace-row-6",
            "recordId": "active-workplace-record-6",
            "cells": {
              "workspace": "West region rollout - Completed preview",
              "owner": "Maya Chen",
              "participants": 13,
              "health": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "updated": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 38,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "active-workplace-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Workspace activity",
        "hasMore": true,
        "items": [
          {
            "id": "active-workplace-event-1",
            "recordId": "active-workplace-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Blocker added",
            "description": "Network approval is blocking the Reno rollout.",
            "actor": "Jordan Lee",
            "tone": "danger"
          },
          {
            "id": "active-workplace-event-2",
            "recordId": "active-workplace-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Blocker added - Follow-up",
            "description": "Network approval is blocking the Reno rollout. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "active-workplace-event-3",
            "recordId": "active-workplace-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Blocker added - West region",
            "description": "Network approval is blocking the Reno rollout. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "active-workplace-event-4",
            "recordId": "active-workplace-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Blocker added - Customer response",
            "description": "Network approval is blocking the Reno rollout. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "active-workplace-event-5",
            "recordId": "active-workplace-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Blocker added - Regional operations review with a deliberately long title",
            "description": "Network approval is blocking the Reno rollout. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "active-workplace-event-6",
            "recordId": "active-workplace-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Blocker added - Completed preview",
            "description": "Network approval is blocking the Reno rollout. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface ActiveWorkplacePresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface ActiveWorkplacePresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: ActiveWorkplacePresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function ActiveWorkplacePresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: ActiveWorkplacePresentationProps) {
  if (error) return <p role="alert">The ActiveWorkplace presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading ActiveWorkplace presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>ActiveWorkplace</p>
        <h1>ActiveWorkplace operations</h1>
        <p>Coordinated workspaces, health, ownership, dependencies, participation, and recent work.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/active-workplace`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "active-workplace-live",
      "_type": "module.active-workplace",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Start with depth 2, at most 100 nodes, conservative stale timing, comments enabled, and playback enabled. Add one default GoClaw watcher only after its represented user and approval policy are correct. Builder settings shape behavior but never replace server authorization.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/active-workplace.html).

---
title: "Record relations"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/record-relations.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Record relations

Explores authorized records as a bounded relationship graph and supports typed relation creation/removal only when both endpoints are editable.

## In brief

- **Runtime key:** module.record-graph
- **Experience:** Connected context
- **Security:** Server-enforced

Use Record Relations to show how people, companies, work, files, conversations, events, and custom records connect without duplicating those records into a separate graph store.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.record-graph. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Explores authorized records as a bounded relationship graph and supports typed relation creation/removal only when both endpoints are editable.

## Key capabilities

- Search visible seed records across modules.
- Traverse secured relationships through bounded depth levels.
- Show nodes, typed edges, module, location, status, activity counts, and favorites.
- Add or remove a typed relation only when both record endpoints and the relation operation are authorized.

## Common uses

- Customer/account 360-degree context.
- Case, project, asset, and work dependency exploration.
- Impact analysis and relationship-first CRM experiences.

## How it connects

The graph is a view over canonical Records and RecordRelations. Opening a node returns to the appropriate native or dynamic module; the graph does not become a competing source of record data.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Every traversed node is independently checked for SaaS, tenant, DataRole, record, and location visibility. Inaccessible nodes and edges are omitted, and mutation requires edit authority on both endpoints.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.record-graph` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

## Copy/paste the complete Record Relations page

The native block provides secured seed-record search, bounded graph traversal, typed edges, relation add/remove, favorites, dynamic fields, and related/contextual Knowledge Core.

```
{
  "blocks": [
    { "_id": "connected-records", "_type": "module.record-graph", "props": {}, "children": [] }
  ]
}
```

### Custom unstyled React graph explorer

The seed picker uses the stable title/RecordId cursor returned by SQL. The graph itself is deliberately bounded to depth 1–5 and 2–200 nodes. `truncated` means the browser has a safe partial graph, not permission to fetch an unbounded one.

```
import { FormEvent, useEffect, useMemo, useState } from "react";
import type { RecordGraphResponse, RecordGraphSearchResponse } from "@buildwithhq/module-sdk";
import { getRecordGraph, searchRecordGraph } from "./api";

const empty: RecordGraphSearchResponse = { contractVersion: 1, pageNumber: 1, pageSize: 50, totalRecords: 0, totalPages: 0, totalIsExact: false, hasMore: false, modules: [], items: [] };
type Cursor = { afterTitle?: string; afterRecordId?: string };

export function UnstyledRecordRelations({ locationId = "", maxDepth = 2, maxNodes = 100 }) {
  const [draft, setDraft] = useState("");
  const [search, setSearch] = useState("");
  const [moduleKey, setModuleKey] = useState("");
  const [cursors, setCursors] = useState<Cursor[]>([{}]);
  const [records, setRecords] = useState<RecordGraphSearchResponse>(empty);
  const [graph, setGraph] = useState<RecordGraphResponse | null>(null);
  const [error, setError] = useState<string | null>(null);
  const cursor = cursors[cursors.length - 1];

  useEffect(() => {
    const controller = new AbortController();
    searchRecordGraph(moduleKey, search, locationId, controller.signal, cursor.afterTitle, cursor.afterRecordId, 50)
      .then(setRecords)
      .catch((caught: unknown) => { if (!controller.signal.aborted) setError(caught instanceof Error ? caught.message : "Records could not be loaded."); });
    return () => controller.abort();
  }, [cursor.afterRecordId, cursor.afterTitle, locationId, moduleKey, search]);

  const byId = useMemo(() => new Map(graph?.nodes.map(node => [node.recordId, node]) || []), [graph]);
  function submit(event: FormEvent) { event.preventDefault(); setCursors([{}]); setGraph(null); setSearch(draft.trim()); }
  async function open(recordId: string) { setGraph(await getRecordGraph(recordId, maxDepth, undefined, maxNodes)); }
  function next() { if (records.hasMore && records.nextRecordId) setCursors(current => [...current, { afterTitle: records.nextTitle || undefined, afterRecordId: records.nextRecordId || undefined }]); }

  return <section className="custom-record-relations">
    <h1>Record relations</h1>
    <form role="search" onSubmit={submit}><label>Find a starting record<input value={draft} maxLength={200} onChange={event => setDraft(event.target.value)} /></label><label>Module<select value={moduleKey} onChange={event => { setModuleKey(event.target.value); setCursors([{}]); }}><option value="">All modules</option>{records.modules.map(module => <option key={module.moduleKey} value={module.moduleKey}>{module.moduleName}</option>)}</select></label><button>Search</button></form>
    {error && <p role="alert">{error}</p>}
    <div className="relation-columns"><aside><ol>{records.items.map(record => <li key={record.recordId}><button onClick={() => void open(record.recordId)}><strong>{record.title}</strong><span>{record.moduleName} - {record.locationName || "All locations"}</span></button></li>)}</ol><nav aria-label="Record result pages"><button disabled={cursors.length === 1} onClick={() => setCursors(current => current.slice(0, -1))}>Previous</button><span>Batch {cursors.length}</span><button disabled={!records.hasMore || !records.nextRecordId} onClick={next}>Next</button></nav></aside><main>{graph ? <><header><h2>{byId.get(graph.seedRecordId)?.title || "Record graph"}</h2><p>{graph.nodeCount} nodes - {graph.edges.length} edges - depth {graph.depthReached}{graph.truncated ? " - truncated at the requested limit" : ""}</p></header><section><h3>Nodes</h3>{graph.nodes.map(node => <button key={node.recordId} onClick={() => void open(node.recordId)}><strong>{node.title}</strong><span>Depth {node.depth} - {node.moduleName}</span></button>)}</section><section><h3>Edges</h3>{graph.edges.map(edge => <p key={edge.recordRelationId}><strong>{byId.get(edge.fromRecordId)?.title || "Unavailable"}</strong> - {edge.relationName || edge.relationKey || "Related"} - <strong>{byId.get(edge.toRecordId)?.title || "Unavailable"}</strong></p>)}</section></> : <p>Select a record.</p>}</main></div>
  </section>;
}
```

### Add/remove typed relations and favorite the seed

Use only relation keys returned in `graph.relationTypes`. The helper checks the displayed edit flags for a good UI, while SQL independently reauthorizes both endpoints and the relation operation.

```
import type { RecordGraphResponse } from "@buildwithhq/module-sdk";
import { addRecordGraphRelation, getRecordGraph, removeRecordGraphRelation, setRecordGraphFavorite } from "./api";

export async function connectRecords(graph: RecordGraphResponse, toRecordId: string, relationKey: string) {
  const from = graph.nodes.find(node => node.recordId === graph.seedRecordId);
  const to = graph.nodes.find(node => node.recordId === toRecordId);
  if (!from?.canEdit || !to?.canEdit) throw new Error("Both visible records must be editable.");
  if (!graph.relationTypes.some(type => type.relationKey === relationKey)) throw new Error("Choose a returned relation type.");
  await addRecordGraphRelation(from.recordId, { toRecordId, relationKey });
  return getRecordGraph(from.recordId, 2, undefined, 100);
}

export async function disconnectRecords(seedRecordId: string, recordRelationId: string) {
  await removeRecordGraphRelation(recordRelationId);
  return getRecordGraph(seedRecordId, 2, undefined, 100);
}

export async function toggleGraphFavorite(graph: RecordGraphResponse) {
  const seed = graph.nodes.find(node => node.recordId === graph.seedRecordId);
  if (!seed) throw new Error("The seed record is not visible.");
  await setRecordGraphFavorite(seed.recordId, !seed.isFavorite);
  return getRecordGraph(seed.recordId, 2, undefined, 100);
}
```

### Related and contextual Knowledge Core

Direct relations and bounded graph candidates are distinct. Set `requireAiRead: true` when assembling AI context so candidates must pass the additional AI-read gate; normal record visibility alone is not enough.

```
import { getContextualKnowledge, getRelatedKnowledge, linkKnowledgeToRecord, unlinkKnowledgeFromRecord } from "./api";

export async function loadRecordKnowledge(recordId: string) {
  const [direct, aiCandidates] = await Promise.all([
    getRelatedKnowledge(recordId, 25),
    getContextualKnowledge(recordId, true, 25),
  ]);
  return { direct: direct.items, aiCandidates: aiCandidates.items };
}

export async function linkApprovedKnowledge(recordId: string, knowledgeRecordId: string) {
  return linkKnowledgeToRecord(recordId, { knowledgeRecordId, relationKey: "related-knowledge" });
}

export async function unlinkApprovedKnowledge(recordRelationId: string) {
  return unlinkKnowledgeFromRecord(recordRelationId);
}
```

### Optional starter styling

```
.custom-record-relations { width: 100%; max-width: none; }
.custom-record-relations > form, .relation-columns nav { align-items: end; display: flex; flex-wrap: wrap; gap: .75rem; }
.relation-columns { display: grid; gap: 1rem; grid-template-columns: 280px minmax(0, 1fr); margin-top: 1rem; }
.relation-columns ol { list-style: none; margin: 0; padding: 0; }
.relation-columns aside li button, .relation-columns main section button { background: transparent; border: 0; display: grid; padding: .65rem; text-align: left; width: 100%; }
.relation-columns main { border: 1px solid var(--line, #d8dee8); padding: 1rem; }
.relation-columns main section { border-top: 1px solid var(--line, #d8dee8); padding-top: .75rem; }
@media (max-width: 760px) { .relation-columns { grid-template-columns: 1fr; } }
```

### Exact data path

| Purpose | Route | Procedure |
| --- | --- | --- |
| Cursor seed search | `GET /api/modules/record-graph/records` | `sp_RecordGraph_SearchSecured` |
| Bounded graph | `GET /api/modules/record-graph/{recordId}` | `sp_RecordGraph_GetSecured` |
| Add/remove relation | `PUT /{recordId}/relations`, `DELETE /relations/{recordRelationId}` | `sp_RecordGraph_AddRelationSecured`, `sp_RecordGraph_RemoveRelationSecured` |
| Favorite | `PUT /{recordId}/favorite` | `sp_Favorites_SetSecured` |
| Knowledge reads | `GET /{recordId}/knowledge`, `GET /{recordId}/knowledge/candidates` | `sp_kc_GetRelatedKnowledgeSecured`, `sp_kc_GetContextualKnowledgeCandidatesSecured` |
| Knowledge link/unlink | `PUT /{recordId}/knowledge`, `DELETE /knowledge-relations/{recordRelationId}` | `sp_kc_LinkKnowledgeToRecord`, `sp_kc_UnlinkKnowledgeFromRecord` |

The canonical `RecordRelations` rows are the relationship source. BuildWithHQ does not require a massive pre-expanded user/role/location graph table: each bounded read intersects current record, DataRole, location, direct-conversation, and AI-read policy before returning nodes or knowledge.

## Build a professional Record relations dashboard

These six registry-backed presentation blocks let a designer turn the secured Record relations API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/record-graph`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/record-relations-sample.json`, its executable authenticated page at `pages/first-class/record-relations-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Record relations projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Visible relations, connected records, types, and recent links |
| `entity-list` | `core.entity-list` | Highly connected records inside the current scope |
| `progress-list` | `core.progress-list` | Distribution by relation type or owning module |
| `series-chart` | `core.series-chart` | Relationship creation and removal |
| `data-grid` | `core.presentation-grid` | One bounded edge page with both endpoints authorized |
| `timeline` | `core.timeline` | Create, update, remove, source loss, and graph traversal events |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "record-relations-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Relationship overview",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "relations",
            "label": "Visible relations",
            "value": 3218,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "records",
            "label": "Connected records",
            "value": 1407,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "types",
            "label": "Relation types",
            "value": 18,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "new",
            "label": "Added this week",
            "value": 96,
            "format": "number",
            "tone": "warning"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "record-relations-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Highly connected records",
        "hasMore": true,
        "items": [
          {
            "id": "record-relations-sample-1",
            "recordId": "record-relations-record-1",
            "primary": "Acme Field Services",
            "secondary": "Contact - 34 visible relations",
            "status": {
              "key": "connected",
              "label": "Connected",
              "tone": "success"
            },
            "trailing": "34 links"
          },
          {
            "id": "record-relations-sample-2",
            "recordId": "record-relations-record-2",
            "primary": "Acme Field Services - Follow-up",
            "secondary": "Contact - 34 visible relations - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "record-relations-sample-3",
            "recordId": "record-relations-record-3",
            "primary": "Acme Field Services - West region",
            "secondary": "Contact - 34 visible relations - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "record-relations-sample-4",
            "recordId": "record-relations-record-4",
            "primary": "Acme Field Services - Customer response",
            "secondary": "Contact - 34 visible relations - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "record-relations-sample-5",
            "recordId": "record-relations-record-5",
            "primary": "Acme Field Services - Regional operations review with a deliberately long title",
            "secondary": "Contact - 34 visible relations - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "record-relations-sample-6",
            "recordId": "record-relations-record-6",
            "primary": "Acme Field Services - Completed preview",
            "secondary": "Contact - 34 visible relations - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "record-relations-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Relations by type",
        "items": [
          {
            "key": "customer",
            "label": "Customer of",
            "value": 1210,
            "maximum": 3218,
            "displayValue": "1210",
            "tone": "primary",
            "status": {
              "key": "customer",
              "label": "Customer of",
              "tone": "primary"
            }
          },
          {
            "key": "attached",
            "label": "Attached to",
            "value": 1084,
            "maximum": 3218,
            "displayValue": "1084",
            "tone": "success",
            "status": {
              "key": "attached",
              "label": "Attached to",
              "tone": "success"
            }
          },
          {
            "key": "depends",
            "label": "Depends on",
            "value": 924,
            "maximum": 3218,
            "displayValue": "924",
            "tone": "warning",
            "status": {
              "key": "depends",
              "label": "Depends on",
              "tone": "warning"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "record-relations-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Relationship activity",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Created",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Removed",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "record-relations-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Visible relationships",
        "columns": [
          {
            "key": "from",
            "label": "From",
            "type": "text",
            "align": "left"
          },
          {
            "key": "relation",
            "label": "Relationship",
            "type": "text",
            "align": "left"
          },
          {
            "key": "to",
            "label": "To",
            "type": "text",
            "align": "left"
          },
          {
            "key": "status",
            "label": "Status",
            "type": "status",
            "align": "left"
          },
          {
            "key": "created",
            "label": "Created",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "record-relations-row-1",
            "recordId": "record-relations-record-1",
            "cells": {
              "from": "Acme Field Services",
              "relation": "Customer of",
              "to": "WO-1048",
              "status": {
                "key": "active",
                "label": "Active",
                "tone": "success"
              },
              "created": "2026-09-04T11:11:00Z"
            }
          },
          {
            "id": "record-relations-row-2",
            "recordId": "record-relations-record-2",
            "cells": {
              "from": "Acme Field Services - Follow-up",
              "relation": "Customer of",
              "to": "WO-1048",
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "created": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "record-relations-row-3",
            "recordId": "record-relations-record-3",
            "cells": {
              "from": "Acme Field Services - West region",
              "relation": "Customer of",
              "to": "WO-1048",
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "created": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "record-relations-row-4",
            "recordId": "record-relations-record-4",
            "cells": {
              "from": "Acme Field Services - Customer response",
              "relation": "Customer of",
              "to": "WO-1048",
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "created": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "record-relations-row-5",
            "recordId": "record-relations-record-5",
            "cells": {
              "from": "Acme Field Services - Regional operations review with a deliberately long title",
              "relation": "Customer of - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "to": "WO-1048",
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "created": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "record-relations-row-6",
            "recordId": "record-relations-record-6",
            "cells": {
              "from": "Acme Field Services - Completed preview",
              "relation": "Customer of",
              "to": "WO-1048",
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "created": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 3218,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "record-relations-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Relationship activity",
        "hasMore": true,
        "items": [
          {
            "id": "record-relations-event-1",
            "recordId": "record-relations-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Relationship created",
            "description": "Acme Field Services was related to WO-1048.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "record-relations-event-2",
            "recordId": "record-relations-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Relationship created - Follow-up",
            "description": "Acme Field Services was related to WO-1048. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "record-relations-event-3",
            "recordId": "record-relations-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Relationship created - West region",
            "description": "Acme Field Services was related to WO-1048. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "record-relations-event-4",
            "recordId": "record-relations-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Relationship created - Customer response",
            "description": "Acme Field Services was related to WO-1048. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "record-relations-event-5",
            "recordId": "record-relations-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Relationship created - Regional operations review with a deliberately long title",
            "description": "Acme Field Services was related to WO-1048. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "record-relations-event-6",
            "recordId": "record-relations-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Relationship created - Completed preview",
            "description": "Acme Field Services was related to WO-1048. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface RecordRelationsPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface RecordRelationsPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: RecordRelationsPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function RecordRelationsPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: RecordRelationsPresentationProps) {
  if (error) return <p role="alert">The Record relations presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Record relations presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Record relations</p>
        <h1>Relationship overview</h1>
        <p>Authorized connections, relation types, highly connected records, and graph changes.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/record-graph`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "record-relations-live",
      "_type": "module.record-graph",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Keep relation types meaningful and limited. A consistent typed relationship vocabulary produces better navigation, automation, and AI context than many near-duplicate labels.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/record-relations.html).

---
title: "Record activity"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/record-activity.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Record activity

Shows a paged, filterable, chronological activity timeline for an authorized record with actor, event type/state, date range, relations, and favorite state.

## In brief

- **Runtime key:** module.record-activity
- **Experience:** Timeline & history
- **Security:** Server-enforced

Use Record Activity to give users an understandable operational history of what happened around a record without exposing raw database auditing or internal event payloads.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.record-activity. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Shows a paged, filterable, chronological activity timeline for an authorized record with actor, event type/state, date range, relations, and favorite state.

## Key capabilities

- Search visible records across modules and select a record timeline.
- Filter activity by event type and date range.
- Group events chronologically with summary, actor, state, and occurrence time.
- Page bounded history and show secured relation/favorite context.

## Common uses

- Customer, project, work-order, case, and asset timelines.
- Operational handoffs and investigation context.
- A user-facing history adjacent to formal compliance/audit evidence.

## How it connects

Activity aggregates the reviewed events emitted by native and dynamic records. Formal security/compliance evidence remains in its audit contracts; the activity module provides the bounded business-facing view.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

The selected record must pass normal scope checks, and only safe activity summaries/metadata are rendered. Private event detail payloads stay outside the browser surface.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.record-activity` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

## Copy/paste the complete Record Activity page

The native block supplies secured record selection, event/date filtering, bounded timeline pages, actor/state summaries, dynamic fields, relation counts, and favorites.

```
{
  "blocks": [
    { "_id": "record-history", "_type": "module.record-activity", "props": {}, "children": [] }
  ]
}
```

### Custom unstyled React record picker and timeline

The record picker uses the stable title/RecordId cursor. After selection, activity uses independent pages of at most 100 safe event summaries. This component deliberately does not render the internal `detail` object.

```
import { FormEvent, useEffect, useState } from "react";
import type { RecordActivityResponse, RecordActivitySearchResponse } from "@buildwithhq/module-sdk";
import { getRecordActivity, searchRecordActivity } from "./api";

const empty: RecordActivitySearchResponse = { contractVersion: 1, pageNumber: 1, pageSize: 50, totalRecords: 0, totalPages: 0, totalIsExact: false, hasMore: false, modules: [], items: [] };
type Cursor = { afterTitle?: string; afterRecordId?: string };
const startOfDayUtc = (date: string) => date ? `${date}T00:00:00.000Z` : "";
const endOfDayUtc = (date: string) => date ? `${date}T23:59:59.999Z` : "";

export function UnstyledRecordActivity({ locationId = "" }) {
  const [draft, setDraft] = useState("");
  const [search, setSearch] = useState("");
  const [moduleKey, setModuleKey] = useState("");
  const [cursors, setCursors] = useState<Cursor[]>([{}]);
  const [records, setRecords] = useState<RecordActivitySearchResponse>(empty);
  const [activity, setActivity] = useState<RecordActivityResponse | null>(null);
  const [activityType, setActivityType] = useState("");
  const [fromDate, setFromDate] = useState("");
  const [toDate, setToDate] = useState("");
  const [error, setError] = useState<string | null>(null);
  const cursor = cursors[cursors.length - 1];

  useEffect(() => {
    const controller = new AbortController();
    searchRecordActivity(moduleKey, search, locationId, controller.signal, cursor.afterTitle, cursor.afterRecordId, 50)
      .then(setRecords)
      .catch((caught: unknown) => { if (!controller.signal.aborted) setError(caught instanceof Error ? caught.message : "Records could not be loaded."); });
    return () => controller.abort();
  }, [cursor.afterRecordId, cursor.afterTitle, locationId, moduleKey, search]);

  async function loadTimeline(recordId: string, page = 1) { setActivity(await getRecordActivity(recordId, activityType, startOfDayUtc(fromDate), endOfDayUtc(toDate), page, undefined, 50)); }
  function submit(event: FormEvent) { event.preventDefault(); setCursors([{}]); setActivity(null); setSearch(draft.trim()); }
  function nextRecords() { if (records.hasMore && records.nextRecordId) setCursors(current => [...current, { afterTitle: records.nextTitle || undefined, afterRecordId: records.nextRecordId || undefined }]); }

  return <section className="custom-record-activity">
    <h1>Record activity</h1>
    <form role="search" onSubmit={submit}><label>Find a record<input value={draft} maxLength={200} onChange={event => setDraft(event.target.value)} /></label><label>Module<select value={moduleKey} onChange={event => { setModuleKey(event.target.value); setCursors([{}]); }}><option value="">All modules</option>{records.modules.map(module => <option key={module.moduleKey} value={module.moduleKey}>{module.moduleName}</option>)}</select></label><button>Search</button></form>
    {error && <p role="alert">{error}</p>}
    <div className="activity-columns"><aside><ol>{records.items.map(record => <li key={record.recordId}><button onClick={() => void loadTimeline(record.recordId)}><strong>{record.title}</strong><span>{record.moduleName}{record.locationName ? ` - ${record.locationName}` : ""}</span></button></li>)}</ol><nav aria-label="Record batches"><button disabled={cursors.length === 1} onClick={() => setCursors(current => current.slice(0, -1))}>Previous</button><span>Batch {cursors.length}</span><button disabled={!records.hasMore || !records.nextRecordId} onClick={nextRecords}>Next</button></nav></aside><main>{activity ? <><header><h2>{activity.title}</h2><p>{activity.moduleName} - {activity.recordStatus || "No status"} - {activity.relationCount} relations</p></header><form onSubmit={event => { event.preventDefault(); void loadTimeline(activity.recordId, 1); }}><label>Event type<select value={activityType} onChange={event => setActivityType(event.target.value)}><option value="">All</option>{activity.activityTypes.map(type => <option key={type.activityType}>{type.activityType}</option>)}</select></label><label>From<input type="date" value={fromDate} onChange={event => setFromDate(event.target.value)} /></label><label>To<input type="date" min={fromDate || undefined} value={toDate} onChange={event => setToDate(event.target.value)} /></label><button>Apply</button></form><ol className="timeline">{activity.items.map(item => <li key={item.activityKey}><strong>{item.summary}</strong><span>{item.activityType}{item.activityState ? ` - ${item.activityState}` : ""}</span><small>{item.actorDisplayName || "System"} - <time dateTime={item.occurredUtc}>{new Date(item.occurredUtc).toLocaleString()}</time></small></li>)}</ol><nav aria-label="Timeline pages"><button disabled={activity.pageNumber <= 1} onClick={() => void loadTimeline(activity.recordId, activity.pageNumber - 1)}>Previous</button><span>Page {activity.pageNumber} of {Math.max(1, activity.totalPages)}</span><button disabled={activity.pageNumber >= activity.totalPages} onClick={() => void loadTimeline(activity.recordId, activity.pageNumber + 1)}>Next</button></nav></> : <p>Select a record.</p>}</main></div>
  </section>;
}
```

### Metadata change history

Supported native record pages can show a separate change-history panel. Its signed-in tenant route is `GET /api/modules/record-activity/{recordId}/history`; it is not part of the published Developer API. It returns event ID, change type, actor user ID and occurrence time, without stored field values or before/after snapshots. Use `pageSize` (default 25, maximum 100) and pass the returned `nextBeforeId` string as `beforeId` when `hasMore` is true.

The service rechecks current record authority before and after reading the app's routed Logs database. Personal ownership, DataRole and location rules still apply; access to this page or an old event does not grant access to the record. A missing location label is omitted rather than interpreted as All locations. History coverage depends on the owning module and action: the native Work Order status and assignment actions, Web Link creates/updates and dynamic record creates/updates have been verified; this does not promise that every module action emits a change event.

### Favorite the source record

Activity is read-only by design. There is no generic “create activity” route: Contacts, Work Orders, workflows, Conversations, and other owning modules emit reviewed business events as their real operations occur.

```
import type { RecordActivityResponse } from "@buildwithhq/module-sdk";
import { getRecordActivity, setRecordActivityFavorite } from "./api";

export async function toggleActivityRecordFavorite(current: RecordActivityResponse) {
  await setRecordActivityFavorite(current.recordId, !current.isFavorite);
  return getRecordActivity(current.recordId, "", "", "", 1, undefined, 50);
}
```

### Optional starter styling

```
.custom-record-activity { width: 100%; max-width: none; }
.custom-record-activity > form, .activity-columns form, .activity-columns nav { align-items: end; display: flex; flex-wrap: wrap; gap: .75rem; }
.activity-columns { display: grid; gap: 1rem; grid-template-columns: 280px minmax(0, 1fr); margin-top: 1rem; }
.activity-columns ol { list-style: none; margin: 0; padding: 0; }
.activity-columns aside li button { background: transparent; border: 0; display: grid; padding: .65rem; text-align: left; width: 100%; }
.activity-columns main { border: 1px solid var(--line, #d8dee8); padding: 1rem; }
.timeline li { border-left: 3px solid var(--accent, #4967d5); display: grid; gap: .2rem; margin: .75rem 0; padding: .25rem .75rem; }
@media (max-width: 760px) { .activity-columns { grid-template-columns: 1fr; } }
```

### Exact data path

| Purpose | Route | Procedure |
| --- | --- | --- |
| Cursor record search | `GET /api/modules/record-activity/records` | `sp_RecordActivity_SearchSecured` |
| Paged safe timeline | `GET /api/modules/record-activity/{recordId}` | `sp_RecordActivity_GetSecured` |
| Metadata change history (native tenant route) | `GET /api/modules/record-activity/{recordId}/history` | Core `sp_RecordActivity_GetSecured` authority checks, then Logs `sp_RecordHistory_ReadInternal` |
| Favorite source | `PUT /api/modules/record-activity/{recordId}/favorite` | `sp_Favorites_SetSecured` |

Record search accepts up to 200 rows but the example uses 50; timeline detail accepts up to 100. This user-facing history is not the immutable security/audit log, and safe summaries should not expose raw event payloads.

## Build a professional Record activity dashboard

These six registry-backed presentation blocks let a designer turn the secured Record activity API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/record-activity`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/record-activity-sample.json`, its executable authenticated page at `pages/first-class/record-activity-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Record activity projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Event volume, creates, updates, workflow, and attention counts |
| `entity-list` | `core.entity-list` | Records with the newest visible activity |
| `progress-list` | `core.progress-list` | Distribution by module, event type, actor, or state |
| `series-chart` | `core.series-chart` | Created, updated, related, approved, and completed events |
| `data-grid` | `core.presentation-grid` | One bounded safe-summary event page |
| `timeline` | `core.timeline` | Chronological safe summaries without private event payloads |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "record-activity-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Record activity overview",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "events",
            "label": "Events today",
            "value": 486,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "creates",
            "label": "Records created",
            "value": 74,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "updates",
            "label": "Records updated",
            "value": 361,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "attention",
            "label": "Attention events",
            "value": 12,
            "format": "number",
            "tone": "warning"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "record-activity-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Recently active records",
        "hasMore": true,
        "items": [
          {
            "id": "record-activity-sample-1",
            "recordId": "record-activity-record-1",
            "primary": "WO-1048 - North Wing closeout",
            "secondary": "Work Orders - 8 events",
            "status": {
              "key": "updated",
              "label": "Updated",
              "tone": "primary"
            },
            "trailing": "2 min ago"
          },
          {
            "id": "record-activity-sample-2",
            "recordId": "record-activity-record-2",
            "primary": "WO-1048 - North Wing closeout - Follow-up",
            "secondary": "Work Orders - 8 events - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "record-activity-sample-3",
            "recordId": "record-activity-record-3",
            "primary": "WO-1048 - North Wing closeout - West region",
            "secondary": "Work Orders - 8 events - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "record-activity-sample-4",
            "recordId": "record-activity-record-4",
            "primary": "WO-1048 - North Wing closeout - Customer response",
            "secondary": "Work Orders - 8 events - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "record-activity-sample-5",
            "recordId": "record-activity-record-5",
            "primary": "WO-1048 - North Wing closeout - Regional operations review with a deliberately long title",
            "secondary": "Work Orders - 8 events - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "record-activity-sample-6",
            "recordId": "record-activity-record-6",
            "primary": "WO-1048 - North Wing closeout - Completed preview",
            "secondary": "Work Orders - 8 events - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "record-activity-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Activity by module",
        "items": [
          {
            "key": "work",
            "label": "Work Orders",
            "value": 181,
            "maximum": 486,
            "displayValue": "181",
            "tone": "primary",
            "status": {
              "key": "work",
              "label": "Work Orders",
              "tone": "primary"
            }
          },
          {
            "key": "contacts",
            "label": "Contacts",
            "value": 163,
            "maximum": 486,
            "displayValue": "163",
            "tone": "success",
            "status": {
              "key": "contacts",
              "label": "Contacts",
              "tone": "success"
            }
          },
          {
            "key": "files",
            "label": "Files",
            "value": 142,
            "maximum": 486,
            "displayValue": "142",
            "tone": "neutral",
            "status": {
              "key": "files",
              "label": "Files",
              "tone": "neutral"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "record-activity-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Activity volume",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Created",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Updated",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "record-activity-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Authorized activity events",
        "columns": [
          {
            "key": "record",
            "label": "Record",
            "type": "text",
            "align": "left"
          },
          {
            "key": "module",
            "label": "Module",
            "type": "text",
            "align": "left"
          },
          {
            "key": "event",
            "label": "Event",
            "type": "text",
            "align": "left"
          },
          {
            "key": "actor",
            "label": "Actor",
            "type": "text",
            "align": "left"
          },
          {
            "key": "occurred",
            "label": "Occurred",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "record-activity-row-1",
            "recordId": "record-activity-record-1",
            "cells": {
              "record": "WO-1048",
              "module": "Work Orders",
              "event": "Status changed",
              "actor": "Maya Chen",
              "occurred": "2026-09-04T17:57:00Z"
            }
          },
          {
            "id": "record-activity-row-2",
            "recordId": "record-activity-record-2",
            "cells": {
              "record": "WO-1048 - Follow-up",
              "module": "Work Orders",
              "event": "Status changed",
              "actor": "Maya Chen",
              "occurred": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "record-activity-row-3",
            "recordId": "record-activity-record-3",
            "cells": {
              "record": "WO-1048 - West region",
              "module": "Work Orders",
              "event": "Status changed",
              "actor": "Maya Chen",
              "occurred": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "record-activity-row-4",
            "recordId": "record-activity-record-4",
            "cells": {
              "record": "WO-1048 - Customer response",
              "module": "Work Orders",
              "event": "Status changed",
              "actor": "Maya Chen",
              "occurred": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "record-activity-row-5",
            "recordId": "record-activity-record-5",
            "cells": {
              "record": "WO-1048 - Regional operations review with a deliberately long title",
              "module": "Work Orders - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "event": "Status changed",
              "actor": "Maya Chen",
              "occurred": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "record-activity-row-6",
            "recordId": "record-activity-record-6",
            "cells": {
              "record": "WO-1048 - Completed preview",
              "module": "Work Orders",
              "event": "Status changed",
              "actor": "Maya Chen",
              "occurred": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 486,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "record-activity-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Recent authorized activity",
        "hasMore": true,
        "items": [
          {
            "id": "record-activity-event-1",
            "recordId": "record-activity-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Status changed",
            "description": "WO-1048 moved from In progress to Ready for signoff.",
            "actor": "Maya Chen",
            "tone": "primary"
          },
          {
            "id": "record-activity-event-2",
            "recordId": "record-activity-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Status changed - Follow-up",
            "description": "WO-1048 moved from In progress to Ready for signoff. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "record-activity-event-3",
            "recordId": "record-activity-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Status changed - West region",
            "description": "WO-1048 moved from In progress to Ready for signoff. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "record-activity-event-4",
            "recordId": "record-activity-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Status changed - Customer response",
            "description": "WO-1048 moved from In progress to Ready for signoff. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "record-activity-event-5",
            "recordId": "record-activity-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Status changed - Regional operations review with a deliberately long title",
            "description": "WO-1048 moved from In progress to Ready for signoff. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "record-activity-event-6",
            "recordId": "record-activity-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Status changed - Completed preview",
            "description": "WO-1048 moved from In progress to Ready for signoff. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface RecordActivityPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface RecordActivityPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: RecordActivityPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function RecordActivityPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: RecordActivityPresentationProps) {
  if (error) return <p role="alert">The Record activity presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Record activity presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Record activity</p>
        <h1>Record activity overview</h1>
        <p>Safe event summaries, actors, source modules, status changes, and recent authorized history.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/record-activity`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "record-activity-live",
      "_type": "module.record-activity",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Write concise activity summaries when workflows change important state. Users should understand the event without needing internal JSON or database knowledge.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/record-activity.html).

---
title: "Global secured search"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/global-search.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Global secured search

Searches permitted records across modules and also uses permission-filtered vector retrieval to find meaningfully related information in indexed uploads, PDFs, images, screenshots, tables, diagrams, and text.

## In brief

- **Runtime key:** module.global-search
- **Experience:** Cross-module discovery
- **Security:** Server-enforced

Use Global Search as the universal finder when users need to locate customers, files, work, conversations, events, custom records, or related evidence from uploaded content in one place.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.global-search. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Searches permitted records across modules and also uses permission-filtered vector retrieval to find meaningfully related information in indexed uploads, PDFs, images, screenshots, tables, diagrams, and text.

## Key capabilities

- Run bounded text search across authorized modules and records.
- Search eligible indexed uploads, PDFs, images, screenshots, tables, diagrams, and extracted text in a shared vector space.
- Find conceptually related information even when the source uses different words from the query.
- Retrieve the original text, page, image, and source identity so results can retain evidence and citations.
- Filter by module and page through stable result envelopes.
- Show safe matched-field snippets plus module, status, location, relation, activity, and update context.
- Add or remove favorites without leaving the result list.

## How vector and AI search improve discovery

Global Search has two complementary secured paths. Operational record search is best for exact names, identifiers, fields, statuses, and module records. The AI search path vectorizes eligible indexed content so a query can match by meaning, not only by identical keywords.

| Search path | What it finds | Why it helps |
| --- | --- | --- |
| Record and keyword | Exact or close text in permitted records and fields | Fast, predictable lookup for known business data. |
| Semantic vector | Related passages and documents that express the same idea with different wording | Surfaces useful context that keyword-only search can miss. |
| Multimodal vector | Relevant uploads, PDF pages, images, screenshots, charts, tables, and diagrams | Lets a text question find visual evidence, including information that weak OCR or text extraction may lose. |
| AI relevance and reranking | The strongest authorized candidates, with their original source and page context | Brings more closely related information toward the top while preserving evidence for review. |

For example, a search for *declining renewal risk* can surface a customer record, a differently worded conversation, a chart on an uploaded PDF page, and a screenshot containing relevant evidence—provided each source is indexed, AI-eligible, and visible to the current user.

AI relevance is a discovery aid, not proof that every result is correct. Users can open the original source, page, or visual evidence to verify the result in context.

## Common uses

- App-wide command and search experiences.
- Finding a record when its owning module is unknown.
- Discovering related material across records and uploaded documents.
- Finding a PDF page, image, screenshot, chart, table, or diagram from a natural-language description.
- Cross-module navigation in relationship-heavy applications.

## How it connects

Record results point to the canonical record in its owning module. AI search uses the platform's secured source, document-element, chunk, visual-index, and vector retrieval chain; it returns original source/page/asset references instead of copying the evidence into a new business record.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

The server applies SaaS, tenant, CanAiReadRecords, DataRole, location, record, field, and AI-eligibility rules before vector candidates or visual evidence can be returned. Unindexed, deleted, AI-excluded, or otherwise unauthorized content is absent from results. Relevance never grants access, and counts, snippets, citations, and related context must not reveal inaccessible records or fields.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated `module.global-search` module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

## Copy/paste the complete Global Search page

The native block gives users bounded cross-module record search, server-provided matched fields, module/location context, relation/activity counts, paging, and favorites.

```
{
  "blocks": [
    { "_id": "find-anything", "_type": "module.global-search", "props": {}, "children": [] }
  ]
}
```

### Custom unstyled React search

Search requests at most 100 already-authorized rows per page, within a 5,000-match browsing window. Refine filters to reach other records. `includeTotal=false` is the default; `hasMore` is the safe next-page signal. The separate secured count endpoint can return the full authorized total without delaying row rendering. See [progressive loading and exact counts](../api/progressive-loading-and-counts.html); a missing or failed count is not zero. Do not download every module and filter it in the browser.

```
import { FormEvent, useEffect, useRef, useState } from "react";
import type { GlobalSearchItem, GlobalSearchResponse } from "@buildwithhq/module-sdk";
import { searchGlobalRecords } from "./api";

const empty: GlobalSearchResponse = { contractVersion: 1, query: "", pageNumber: 1, pageSize: 50, totalRecords: 0, totalPages: 0, totalIsExact: false, hasMore: false, modules: [], items: [] };

export function UnstyledGlobalSearch({ locationId = "", onOpenRecord }: { locationId?: string; onOpenRecord?: (item: GlobalSearchItem) => void }) {
  const [draft, setDraft] = useState("");
  const [query, setQuery] = useState("");
  const [moduleKey, setModuleKey] = useState("");
  const [page, setPage] = useState(1);
  const [result, setResult] = useState<GlobalSearchResponse>(empty);
  const [error, setError] = useState<string | null>(null);
  const request = useRef(0);

  useEffect(() => {
    const version = ++request.current;
    const controller = new AbortController();
    searchGlobalRecords(query, moduleKey, page, controller.signal, locationId, 50)
      .then(value => { if (version === request.current) setResult(value); })
      .catch((caught: unknown) => { if (!controller.signal.aborted && version === request.current) setError(caught instanceof Error ? caught.message : "Search failed."); });
    return () => controller.abort();
  }, [locationId, moduleKey, page, query]);

  function submit(event: FormEvent) {
    event.preventDefault();
    const normalized = draft.trim();
    if (normalized && normalized.length < 2) { setError("Enter at least two characters."); return; }
    setError(null); setPage(1); setQuery(normalized);
  }

  return <section className="custom-global-search">
    <h1>Search</h1>
    <form role="search" onSubmit={submit}><label>Search all visible records<input value={draft} maxLength={200} onChange={event => setDraft(event.target.value)} /></label><label>Module<select value={moduleKey} onChange={event => { setModuleKey(event.target.value); setPage(1); }}><option value="">All modules</option>{result.modules.map(module => <option key={module.moduleKey} value={module.moduleKey}>{module.moduleName}</option>)}</select></label><button>Search</button></form>
    {error && <p role="alert">{error}</p>}
    <p>{result.totalRecords}{result.totalIsExact ? "" : "+"} visible matches</p>
    <ol>{result.items.map(item => <li key={item.recordId}><article><header><span>{item.moduleName}</span><h2>{item.title}</h2></header><p>{item.recordStatus || "No status"} - {item.locationName || "All locations"}</p><dl>{item.matchedFields.map(field => <div key={field.fieldKey}><dt>{field.fieldLabel}</dt><dd>{field.matchedValue}</dd></div>)}</dl><small>{item.relationCount} relations - {item.activityCount} activity - matched {item.matchKind}</small>{onOpenRecord && <button type="button" onClick={() => onOpenRecord(item)}>Open in {item.moduleName}</button>}</article></li>)}</ol>
    <nav aria-label="Search pages"><button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button><span>Page {result.pageNumber}{result.totalIsExact ? ` of ${Math.max(1, result.totalPages)}` : ""}</span><button disabled={!result.hasMore} onClick={() => setPage(value => value + 1)}>Next</button></nav>
  </section>;
}
```

### Favorite a result without broadening access

The result's `moduleKey` tells the shell which owning module should open it. There is intentionally no generic edit call: writes stay with the owning module's typed API.

```
import type { GlobalSearchItem } from "@buildwithhq/module-sdk";
import { searchGlobalRecords, setGlobalSearchFavorite } from "./api";

export async function toggleSearchFavorite(item: GlobalSearchItem) {
  return setGlobalSearchFavorite(item.recordId, !item.isFavorite);
}

export function reloadCurrentSearch(query: string, moduleKey: string, page: number, locationId = "") {
  return searchGlobalRecords(query, moduleKey, page, undefined, locationId, 50);
}
```

### Optional starter styling

```
.custom-global-search { width: 100%; max-width: none; }
.custom-global-search form, .custom-global-search nav { align-items: end; display: flex; flex-wrap: wrap; gap: .75rem; }
.custom-global-search > ol { list-style: none; margin: 1rem 0; padding: 0; }
.custom-global-search > ol > li { border-bottom: 1px solid var(--line, #d8dee8); padding: 1rem 0; }
.custom-global-search article header { display: flex; gap: .75rem; justify-content: space-between; }
.custom-global-search article dl > div { display: grid; gap: .5rem; grid-template-columns: minmax(110px, 180px) minmax(0, 1fr); }
.custom-global-search article button { margin-top: .75rem; }
```

### Exact data path and the AI-search boundary

| Purpose | Route | Procedure |
| --- | --- | --- |
| Operational record search | `GET /api/modules/global-search` | `sp_GlobalSearch_SearchSecured` |
| Favorite result | `PUT /api/modules/global-search/records/{recordId}/favorite` | `sp_Favorites_SetSecured` |

The component above uses the current operational record-search contract; it does not falsely label a keyword request as vector search. Semantic and multimodal retrieval must use a separately published, validated AI binding that applies `CanAiReadRecords`, DataRole, location, field, source, and AI-eligibility filtering before candidates reach React. Keep interactive lookup bounded; use the governed AI-insights/data-graph path for whole authorized-graph analysis.

## Build a professional Global secured search dashboard

These six registry-backed presentation blocks let a designer turn the secured Global secured search API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at `/api/modules/global-search`; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Installation and component guide](../builder-guide/professional-template-foundation.html) [Complete headless SaaS guide](../api/headless-saas.html)

The ZIP contains this feature's fictional design composition at `pages/first-class/global-search-sample.json`, its executable authenticated page at `pages/first-class/global-search-live.json`, and the catalog-driven `FirstClassPresentationGallery.tsx`. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

| Payload kind | Runtime block | Useful Global secured search projection |
| --- | --- | --- |
| `metric-set` | `core.metric-strip` | Searches, opened results, visual matches, and zero-result counts |
| `entity-list` | `core.entity-list` | Recent results the current user was allowed to open |
| `progress-list` | `core.progress-list` | Distribution by module, content type, or retrieval lane |
| `series-chart` | `core.series-chart` | Searches, result opens, favorites, and follow-on actions |
| `data-grid` | `core.presentation-grid` | One bounded page of safe result titles and snippets |
| `timeline` | `core.timeline` | Query, retrieval, open, favorite, feedback, and permission-loss events |

### Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

**Copy the complete six-block page JSON**

```
{
  "blocks": [
    {
      "_id": "global-search-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Search activity and discovery",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "searches",
            "label": "Searches today",
            "value": 486,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "records",
            "label": "Record results opened",
            "value": 214,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "visual",
            "label": "Visual matches",
            "value": 38,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "zero",
            "label": "Zero-result queries",
            "value": 17,
            "format": "number",
            "tone": "warning"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "global-search-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Recently opened results",
        "hasMore": true,
        "items": [
          {
            "id": "global-search-sample-1",
            "recordId": "global-search-record-1",
            "primary": "North Wing closeout",
            "secondary": "Work Orders - exact and semantic match",
            "status": {
              "key": "relevant",
              "label": "Relevant",
              "tone": "success"
            },
            "trailing": "94%"
          },
          {
            "id": "global-search-sample-2",
            "recordId": "global-search-record-2",
            "primary": "North Wing closeout - Follow-up",
            "secondary": "Work Orders - exact and semantic match - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "global-search-sample-3",
            "recordId": "global-search-record-3",
            "primary": "North Wing closeout - West region",
            "secondary": "Work Orders - exact and semantic match - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "global-search-sample-4",
            "recordId": "global-search-record-4",
            "primary": "North Wing closeout - Customer response",
            "secondary": "Work Orders - exact and semantic match - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "global-search-sample-5",
            "recordId": "global-search-record-5",
            "primary": "North Wing closeout - Regional operations review with a deliberately long title",
            "secondary": "Work Orders - exact and semantic match - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "global-search-sample-6",
            "recordId": "global-search-record-6",
            "primary": "North Wing closeout - Completed preview",
            "secondary": "Work Orders - exact and semantic match - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "global-search-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Results by source",
        "items": [
          {
            "key": "records",
            "label": "Business records",
            "value": 267,
            "maximum": 486,
            "displayValue": "267",
            "tone": "primary",
            "status": {
              "key": "records",
              "label": "Business records",
              "tone": "primary"
            }
          },
          {
            "key": "documents",
            "label": "Documents",
            "value": 143,
            "maximum": 486,
            "displayValue": "143",
            "tone": "success",
            "status": {
              "key": "documents",
              "label": "Documents",
              "tone": "success"
            }
          },
          {
            "key": "visuals",
            "label": "Images and diagrams",
            "value": 76,
            "maximum": 486,
            "displayValue": "76",
            "tone": "neutral",
            "status": {
              "key": "visuals",
              "label": "Images and diagrams",
              "tone": "neutral"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "global-search-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Search and result activity",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Searches",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Results opened",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "global-search-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Recent authorized discoveries",
        "columns": [
          {
            "key": "result",
            "label": "Result",
            "type": "text",
            "align": "left"
          },
          {
            "key": "module",
            "label": "Module",
            "type": "text",
            "align": "left"
          },
          {
            "key": "match",
            "label": "Match",
            "type": "text",
            "align": "left"
          },
          {
            "key": "status",
            "label": "State",
            "type": "status",
            "align": "left"
          },
          {
            "key": "opened",
            "label": "Opened",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "global-search-row-1",
            "recordId": "global-search-record-1",
            "cells": {
              "result": "North Wing closeout",
              "module": "Work Orders",
              "match": "Title and related PDF",
              "status": {
                "key": "relevant",
                "label": "Relevant",
                "tone": "success"
              },
              "opened": "2026-09-04T17:36:00Z"
            }
          },
          {
            "id": "global-search-row-2",
            "recordId": "global-search-record-2",
            "cells": {
              "result": "North Wing closeout - Follow-up",
              "module": "Work Orders",
              "match": "Title and related PDF",
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "opened": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "global-search-row-3",
            "recordId": "global-search-record-3",
            "cells": {
              "result": "North Wing closeout - West region",
              "module": "Work Orders",
              "match": "Title and related PDF",
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "opened": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "global-search-row-4",
            "recordId": "global-search-record-4",
            "cells": {
              "result": "North Wing closeout - Customer response",
              "module": "Work Orders",
              "match": "Title and related PDF",
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "opened": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "global-search-row-5",
            "recordId": "global-search-record-5",
            "cells": {
              "result": "North Wing closeout - Regional operations review with a deliberately long title",
              "module": "Work Orders - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "match": "Title and related PDF",
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "opened": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "global-search-row-6",
            "recordId": "global-search-record-6",
            "cells": {
              "result": "North Wing closeout - Completed preview",
              "module": "Work Orders",
              "match": "Title and related PDF",
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "opened": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 486,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "global-search-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Search activity",
        "hasMore": true,
        "items": [
          {
            "id": "global-search-event-1",
            "recordId": "global-search-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Authorized result opened",
            "description": "North Wing closeout was opened from a permission-filtered search result.",
            "actor": "Maya Chen",
            "tone": "primary"
          },
          {
            "id": "global-search-event-2",
            "recordId": "global-search-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Authorized result opened - Follow-up",
            "description": "North Wing closeout was opened from a permission-filtered search result. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "global-search-event-3",
            "recordId": "global-search-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Authorized result opened - West region",
            "description": "North Wing closeout was opened from a permission-filtered search result. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "global-search-event-4",
            "recordId": "global-search-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Authorized result opened - Customer response",
            "description": "North Wing closeout was opened from a permission-filtered search result. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "global-search-event-5",
            "recordId": "global-search-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Authorized result opened - Regional operations review with a deliberately long title",
            "description": "North Wing closeout was opened from a permission-filtered search result. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "global-search-event-6",
            "recordId": "global-search-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Authorized result opened - Completed preview",
            "description": "North Wing closeout was opened from a permission-filtered search result. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}
```

### Copy/paste React composition

Copy `InteractivePresentationComponents.tsx` and its optional CSS from the [Professional Foundation Developer Kit](../builder-guide/professional-template-foundation.html), then add this module-specific composition. It is semantic and unstyled by default; pass `styled` after importing `interactive-presentation-components.css` for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

```
import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface GlobalSearchPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface GlobalSearchPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: GlobalSearchPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function GlobalSearchPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: GlobalSearchPresentationProps) {
  if (error) return <p role="alert">The Global secured search presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Global secured search presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Global secured search</p>
        <h1>Search activity and discovery</h1>
        <p>Authorized search usage, result types, saved discoveries, visual evidence, and recent queries.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}
```

### Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls `/api/modules/global-search`, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

**Copy the executable live page**

```
{
  "blocks": [
    {
      "_id": "global-search-live",
      "_type": "module.global-search",
      "props": {},
      "children": []
    }
  ]
}
```

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Tip

Keep module-specific filters and lists for focused workflows. Use Global Search as a fast cross-module entry point, and clearly distinguish exact record matches from AI-ranked related evidence so users understand why each result appeared.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/global-search.html).

---
title: "CompanyIQ evidence search"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/company-iq.html"
reviewed_at: "2026-09-14"
authority: Official
---

# CompanyIQ evidence search

Searches approved company records and multimodal sources with citations, and queues only already-authorized records for ingestion.

## In brief

- **Runtime key:** module.company-iq
- **Experience:** Permission-aware company intelligence
- **Security:** Server-enforced

Use the CompanyIQ renderer in a CompanyIQ solution page when analysts need cited company evidence and bounded source ingestion beside complete managed-record lifecycle workspaces.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.company-iq. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Searches approved company records and multimodal sources with citations, and queues only already-authorized records for ingestion.

## Key capabilities

- Run secured 256-to-1024 two-stage or 1998-dimensional retrieval.
- Preserve source record, page, element, and visual references.
- Find only records visible through secured Record Graph search before ingestion.
- Queue durable extraction and embedding through reviewed AI procedures.
- Keep opportunity activation in the governed action chain.

## Common uses

- Evidence-backed customer opportunity review.
- Company document and screenshot discovery.
- Permission-aware source intake.

## How it connects

The renderer uses the existing Records and Record Graph services plus the canonical AI source, document-element, chunk, visual-index, and 256/1024/1998 embedding chain.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

The server derives tenant identity and applies DataRole, location, field, record, source, and CanAiReadRecords policy before retrieval or model context. Search results never grant source access.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Materialize the reviewed CompanyIQ production solution into an owned disposable or provisioned SaaS.
2. Add the validated `module.company-iq` block to a CompanyIQ page through the page editor.
3. Assign server-enforced DataRoles, locations, and AI-read policy, then exercise denied, empty, cited, visual, and source-revocation paths.

Tip

Treat the renderer as evidence retrieval, not mutation authority; route tasks, opportunities, and external actions through normal permissions and approval policy.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/company-iq.html).

---
title: "OpsAtlas operating memory"
section: "First Class Modules"
canonical_url: "https://support.buildwithhq.com/first-class-modules/ops-atlas.html"
reviewed_at: "2026-09-14"
authority: Official
---

# OpsAtlas operating memory

Shows Knowledge Core health, answers operating questions from authorized published evidence, captures unsupported questions as gaps, and queues approved records for multimodal indexing.

## In brief

- **Runtime key:** module.ops-atlas
- **Experience:** Owned and cited operating guidance
- **Security:** Server-enforced

Use the OpsAtlas renderer beside the native Knowledge Core lifecycle when employees need current, role-aware guidance with exact source and visual evidence.

[Open SaaS Apps](https://dev.buildwithhq.com/apps) [Page editor](../builder-guide/page-editor.html) [Menus & user types](../builder-guide/menus-user-types.html) [Templates](../builder-guide/templates-forking.html)

Note

The bundled renderer key is module.ops-atlas. First-class means BuildWithHQ supplies a native, typed, secured runtime experience inside normal app provisioning and the signed-in user's existing permissions.

## What it does

Shows Knowledge Core health, answers operating questions from authorized published evidence, captures unsupported questions as gaps, and queues approved records for multimodal indexing.

## Key capabilities

- Show published, review-due, and gap health from the secured Knowledge Core.
- Return bounded cited answers from current authorized evidence.
- Preserve page, element, source-record, and visual references.
- Capture unsupported questions through the native Knowledge Question workflow instead of guessing.
- Queue only already-visible and AI-readable records for durable indexing.

## Common uses

- Operating-procedure lookup.
- Employee onboarding and policy guidance.
- Knowledge-gap capture and accountable curation.
- Governed agent instruction retrieval.

## How it connects

The renderer uses native Knowledge Core items, immutable revisions, owners, reviews, questions, gaps, files, favorites, relations, and activity plus the canonical multimodal AI pipeline.

Where applicable, its records use the universal `RecordId` conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

## Security and data boundary

Only Published, deliberately AI-eligible material within the represented user's tenant, DataRole, location, field, record, and CanAiReadRecords envelope can become answer context. Material actions remain separately authorized and approval governed.

- The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
- The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
- List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

## Add it to an app

1. Materialize the reviewed OpsAtlas production solution into an owned disposable or provisioned SaaS.
2. Add the validated `module.ops-atlas` block and native `module.knowledge-articles` block to the appropriate pages.
3. Assign Knowledge Core permission keys, owners, DataRoles, locations, and AI-read policy, then test draft exclusion, stale revisions, denied evidence, unsupported questions, and cited visual answers.

Tip

A small current corpus with named owners and exact citations is more valuable than a broad unreviewed document dump.

Important

A renderer being bundled in the tenant application does not make its data visible in every app. The server returns only components and records authorized for the current app and signed-in user; unavailable or unauthorized blocks fail closed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/first-class-modules/ops-atlas.html).

---

# Section: Builder Guide

---
title: "Build and publish SaaS pages"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/page-editor.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build and publish SaaS pages

Build inside your SaaS with Puck, preview safely, and publish an exact validated draft.

## In brief

- **Primary editor:** Puck
- **Advanced editor:** Monaco
- **Publishes:** Validated drafts only

Page design happens inside the SaaS application itself. Open **Design**, select a User Type, then select one of its pages to edit. The same page document can be edited visually in Puck or, when needed, as canonical JSON in Monaco.

Page behavior is anchored to stable identity, not the visible name: BuildWithHQ keeps the page ID internally and uses the reviewed `PageKey` on current authoring and routing contracts. `PageName` is display text and can change without becoming authorization or routing proof.

## Puck is the primary editor

Puck is the normal visual workflow. Add React blocks from the component library, arrange them on the canvas, and edit their validated properties. Styling comes from the app's design system so shared blocks remain consistent. The saved canonical page JSON is independent of the editor, so switching tools does not create a second version of the page.

Use [Monaco advanced JSON mode](raw-json-mode.html)  for precise structural edits or inspection. It edits that same canonical document; it is not a separate page or an authorization shortcut.

## Preview without changing the live app

**Preview** renders the draft in a non-interactive preview surface. You can simulate a selected User Type to check presentation and navigation, but the preview continues to use your current signed-in identity for every data request. It cannot grant the simulated type's DataRoles or Locations, and preview mutations are disabled.

Note

Role simulation answers 'what would this layout show?' It does not answer 'what data may that person access?' Test the published page with a representative signed-in user before release.

## Draft, validate, publish

1. **Save draft** stores the current canonical page only when it has no validation errors.
2. **Validate** checks the latest saved draft against the current component and page contracts.
3. Resolve every error and warning. Publishing requires a valid draft with zero warnings.
4. **Publish** promotes that exact validated draft and version. The public runtime keeps serving the previous published version until promotion succeeds.

Unsaved User Type menu changes block publishing so a page cannot go live against an ambiguous navigation state. Revision history records each saved and published version for inspection and recovery.

## Edit leases and version fences

Only one active editor owns a page's edit lease at a time. The lease renews while you work, and expected-version checks prevent an older browser tab from overwriting newer work. If a lease or version becomes stale, reload the authoring map and review the latest draft before continuing.

## Data-bound blocks stay permission-aware

Data blocks use approved data bindings. Assigning a page to a User Type makes the route eligible for that audience, but it does not grant records, fields, locations, exports, AI context, or actions. Runtime services still authorize each request with the signed-in person's DataRoles, Locations, and other record and action rules.

For the complete creation-to-publish sequence, continue with [Menus and User Types](menus-user-types.html).

## Arrange feature parts

Feature blocks can be split into parts you place anywhere, and one feature can follow the record selected in another. See [Build pages from feature parts](feature-parts.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/page-editor.html).

---
title: "Build pages from feature parts"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/feature-parts.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build pages from feature parts

Split a feature into pieces you place anywhere, put one feature inside another, and build complete solutions such as a customer page with its jobs, appointments and files.

## In brief

- **Where:** Design, in Puck or advanced JSON
- **Applies to:** 14 features
- **Data access:** Unchanged: every piece uses the feature's own permission checks

Every feature block on a page can be split into **parts**: its header, filters, list, detail, form and other pieces. You place the parts wherever your design needs them, and one feature can sit inside another. That is how you build a complete solution, for example a customer page for a home-services business that shows the customer, their jobs, appointments, files and events together.

## Workspaces and parts

A feature block is either its **workspace** or one of its **parts**, chosen by the block property `part`. The workspace loads the data, saves changes and keeps every safety check. Parts only show the piece the workspace hands them, so splitting a screen never splits its data or its permissions.

- Add the feature block once, with no `part`. That is the workspace.
- Inside it, through any layout blocks you like, add the same feature block again with `part` set, for example `"list"` or `"detail"`.
- If you place no parts, the workspace shows its built-in layout exactly as before.

| Feature | Block type | Parts (`props.part`) | Can follow a record |
| --- | --- | --- | --- |
| Contacts | `module.contacts` | header, filters, notices, list, pager, detail, form | Yes |
| Work Orders | `module.work-orders` | header, filters, notices, list, pager, detail, form, payments | Yes |
| Reservations | `module.reservations` | header, filters, notices, list, pager, detail, form, payments | Yes |
| Calendar | `module.calendar` | header, views, filters, notices, list, detail, form | Yes |
| Files | `module.files` | header, filters, notices, list, pager, detail, form, upload | Yes |
| Company News | `module.company-news` | header, filters, notices, list, pager, detail, form | No |
| Web Links | `module.web-links` | header, filters, notices, list, pager, detail, form | No |
| Favorites | `module.favorites` | header, filters, notices, list, pager, detail | No |
| Knowledge Articles | `module.knowledge-articles` | header, notices, health, review, filters, list, pager, detail, form | No |
| Checklists & Sign-offs | `module.checklists-signoffs` | header, notices, filters, list, pager, detail, form, templates | No |
| Chat Rooms | `module.chat-rooms` | header, filters, notices, list, pager, detail, form, thread, members | No |
| Discussion Boards | `module.discussion-boards` | header, filters, notices, list, pager, detail, form, topics, thread | No |
| Conversations | `module.conversations` | header, filters, notices, list, pager, detail, thread, form | No |
| Dynamic Records | `module.dynamic-records` | header, filters, notices, list, pager, detail, form | No |

A few placement rules keep every action reachable:

- A form opens in the `form` part if you placed one, otherwise in `detail`, otherwise in `list`.
- Messages and errors appear at the top of the workspace when you don't place a `notices` part.
- Feature-specific parts you leave out (for example `thread` or `members`) appear inside `detail`.
- A part placed outside its feature's workspace explains where it belongs and loads nothing.
- An unknown `part` value is treated as the workspace.

## Arrange parts in a grid

Use a **Container** block (`core.container`) with `layout` set to `"grid"` and `gridMode` set to `"twelve-column"`. Give each child a `responsive` span per screen size, for example 4 columns for the list and 8 for the detail on desktop, and 12 on tablet and phone so they stack.

Tip

Without `layout: "grid"` and `gridMode: "twelve-column"` a container stacks its children, and the spans have no effect.

## Put one feature inside another

Each workspace shares the record selected in it with the rest of the page under a **context key**. By default the key is the feature's own name (`contacts`, `work-orders` and so on); set `contextKey` to name it yourself, for example `"customer"`.

Another feature follows that record when you set its `recordFrom` to the same key. It then lists only the records linked to the selected one:

- **Work Orders**: jobs whose customer is the selected contact, or that are linked to the selected record.
- **Reservations**: reservations booked for the selected contact, or linked to it.
- **Files**: files attached to the selected record, or linked to it.
- **Calendar**: events linked to the selected record.
- **Contacts**: the customer of a selected work order or the contact of a selected reservation, or contacts linked to it.

Until something is selected, a following workspace loads nothing and says what to select. Set `followEmptyText` to use your own wording. When the selection changes, it reloads from scratch, so nothing from the previous record carries over.

Note

Following never widens access. The person must be able to see the selected record; if they can't, or it was deleted, the following list is empty. Every row still goes through the feature's own permission checks.

Only the workspace that drives the page reads and writes the page address's `?record=` deep link. Following workspaces ignore it, so opening a shared link to a customer never tries to open that customer as a job or a file.

### Example: a home-services customer page

A customer list and detail side by side, with the selected customer's jobs, appointments, files and events below. Paste it into [advanced JSON mode](raw-json-mode.html)  as a starting point.

```
{
  "blocks": [
    { "_id": "customers", "_type": "module.contacts",
      "props": { "title": "Customers", "singular": "customer", "contextKey": "customer", "pageSize": 10 },
      "children": [
        { "_id": "customers-header",  "_type": "module.contacts", "props": { "part": "header" },  "children": [] },
        { "_id": "customers-filters", "_type": "module.contacts", "props": { "part": "filters" }, "children": [] },
        { "_id": "customers-row", "_type": "core.container",
          "props": { "layout": "grid", "gridMode": "twelve-column" },
          "children": [
            { "_id": "customers-list", "_type": "module.contacts",
              "props": { "part": "list", "responsive": { "desktop": { "span": 4 }, "tablet": { "span": 12 }, "mobile": { "span": 12 } } },
              "children": [] },
            { "_id": "customers-detail", "_type": "module.contacts",
              "props": { "part": "detail", "responsive": { "desktop": { "span": 8 }, "tablet": { "span": 12 }, "mobile": { "span": 12 } } },
              "children": [] } ] },
        { "_id": "customers-pager", "_type": "module.contacts", "props": { "part": "pager" }, "children": [] } ] },
    { "_id": "jobs", "_type": "module.work-orders",
      "props": { "title": "Jobs", "recordFrom": "customer", "contextKey": "job",
                 "followEmptyText": "Select a customer to see their jobs." }, "children": [] },
    { "_id": "appointments", "_type": "module.reservations",
      "props": { "title": "Appointments", "recordFrom": "customer",
                 "followEmptyText": "Select a customer to see their appointments." }, "children": [] },
    { "_id": "customer-files", "_type": "module.files",
      "props": { "recordFrom": "customer", "contextKey": "customer-file" }, "children": [] },
    { "_id": "customer-events", "_type": "module.calendar",
      "props": { "recordFrom": "customer", "contextKey": "customer-event" }, "children": [] }
  ]
}
```

## Create in context

When a workspace follows a contact, new records start linked to that contact:

- **New work order** starts with the selected contact as its customer.
- **New reservation** books for the selected contact; the form keeps the email used for follow-ups and skips the new-contact fields.

## Link types

A link type names how two records relate, for example *Jobs* from a customer and *Customer* back from a job. The **Related** panel uses link types when people link records by hand, and the app enforces each type's rules on every new link:

- **Features**: a type can be limited to links from one feature to another, for example from Contacts to Work Orders. A link between other kinds of records is refused.
- **One only**: a type can allow a single linked record per record. A second link of that type is refused until the first is removed; repeating the same link is accepted.
- **Active**: a turned-off type is refused like an unknown one and is hidden from people choosing a link.

The built-in link types (for example the customer of a work order and the contact of a reservation) can't be changed. Links a feature creates itself, such as a new work order's customer, keep working whatever rules you set. Changing a type's rules applies to links made from then on; existing links are kept.

## Rename features

Each app can give a feature its own name, singular and plural, for example *Customer* and *Customers* instead of *Contact* and *Contacts*, or *Student* and *Students* for a school band app. Only the words on screen change; the feature, its data and its permissions stay the same. Clearing both names returns the feature to its built-in name. A block's own `title` still wins on that block.

Set both in **Design**, on the **Links & names** tab. Built-in link types show there read-only; if someone else changed a link type since you opened it, saving asks you to reload first.

Important

Defining link types and renaming features is limited to people who can design the app. Everyone signed in sees the names and the active link types.

## Do the same through the Developer API

- Build and publish these pages with the app design routes under `/v1/apps/{saasAppId}/design`, using your builder keys, exactly as in the designer.
- The Contacts, Work Orders, Reservations, Calendar and Files list operations take an optional `relatedRecordId` query parameter with the same rules as following a record: only linked rows, and an empty list when the caller can't read that record. An all-zero ID is refused with 400. Contacts reports `hasMore` instead of an exact total for a linked list.
- Read and change link types and feature names with your builder keys: `GET /v1/apps/{saasAppId}/design/link-types` returns every link type and every feature with its app name; `PUT /v1/apps/{saasAppId}/design/link-types/{relationKey}` creates or changes a link type (send the `updatedUtc` you were shown when changing one); `PUT /v1/apps/{saasAppId}/design/vocabulary/{moduleKey}` sets or clears a feature's names. Saves change the live app, so they need a live key. Inside the app, the same routes are `/api/runtime/design/link-types` and `/api/runtime/design/vocabulary/{moduleKey}`, and any signed-in user reads the active link types and names from `GET /api/runtime/vocabulary`.
- Bad input is 400; a change to a link type that changed since it was shown, or to a built-in type, is 409.
- Link records with the record graph relation operations; the link type rules above apply. Linking the wrong kinds of records is 422; a second link of a one-only type is 409.

## Not supported yet

- Only Contacts, Work Orders, Reservations, Calendar and Files can follow a record. The other features can be split into parts but don't follow.
- Checklists & Sign-offs shares the selected checklist run, not a record, so other features can't follow a checklist yet.
- Part, context key and follow settings are edited as component properties (or in advanced JSON); dedicated pickers in the designer are still to come.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/feature-parts.html).

---
title: "Build custom data modules"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/dynamic-module-system.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build custom data modules

Model your own business data with Dynamic Records, custom fields and RecordId, then use the same secured records in pages and through the API.

## In brief

- **Data model:** Custom fields on canonical Records
- **Presentation:** Dynamic Records
- **Access:** Personal or DataRole/location permissions

**Dynamic modules let you model business data inside your SaaS without building a specialized feature for every kind of record.** Think of it as a database builder within your application: a module defines a kind of thing, custom fields describe its business information, and each item has a permanent `RecordId`. An asset register, an inspection log or an equipment inventory can use this model.

The business information can consist entirely of custom fields. Standard record identity, title, status, timestamps and visibility still belong to the platform. This is a logical data model within your SaaS database; it does not create a separate SQL database for each module.

## How the pieces fit together

| Piece | What it represents | Example |
| --- | --- | --- |
| Module | A configured business record type, identified by a stable module key | `assets` |
| Field definition | A named, typed piece of business information and its rules | Asset tag, purchase cost, inspection date |
| Record | One item with its own `RecordId`, title and visibility | Warehouse forklift 12 |
| Field value | The value of a defined field on that record | Asset tag FL-012 |
| Page | A published interface for working with the configured module | Asset register list and form |
| UserType | Which menu, homepage and layout a user receives | Employees, Contractors or Customers |

A Contractors UserType and a dynamic module named Contractors are independent choices. A record does not create a login, and putting a page on a UserType menu does not grant access to its records.

## Plan a module from custom fields

Start with one clear record type. For an asset register, the standard title could be *Warehouse forklift 12*, with these custom fields:

| Business field | Type | Example |
| --- | --- | --- |
| Asset tag | Text | FL-012 |
| Purchase cost | Decimal | 24500.00 |
| Next inspection | Date and time | A scheduled inspection date |
| Operational | Yes / no | Yes |
| Condition | Choice | Good, Needs service, Retired |

The current field editor offers Text, Whole number, Decimal, Date and time, Yes / no, Choice and Structured JSON. Choose field keys carefully, use clear labels, and set required behavior, length limits, choices, grouping and order where appropriate. Use record relationships for connections to other records rather than assuming that a text field containing an ID creates a relationship.

## Configure fields and display the module

1. **Start with a configured custom module.** Confirm the module exists in the target app and organization and has its own key. The current product does not provide a standalone create-module wizard or module-definition-create API. Entering a new key in Custom fields does not create a module. Ask the app builder which configured modules are available before adding fields.
2. **Define the shared model.** In **Design**, open a page associated with the module. Its custom-field panel lets authorized designers add builder fields and control whether organizations may add their own fields, with configured limits.
3. **Add organization-specific fields when allowed.** Open **Custom fields**, choose the page and existing module, then choose **Open module fields**. Supply a Key, Label and Type, configure the behavior, and choose **Add field**. Organization field keys use the `c_` prefix. Every read and save checks field-management permission and builder policy.
4. **Display it with Dynamic Records.** Use the `module.dynamic-records` block with the actual configured `moduleKey`. Its standard list, detail and form use the returned field schema. See [Dynamic Records](../first-class-modules/dynamic-records.html)  for the renderer and developer examples, and [Build pages from feature parts](feature-parts.html)  for arranging the workspace.
5. **Publish and test.** Place the page in the intended UserType menus and homepage configuration. Test with users who have different DataRoles and locations, including permitted and denied reads, creates, edits and removals. Field definitions and page publication are separate operations; a page preview alone is not a permission test.

Note

A module may currently have no additional fields. That is an empty custom schema, not a complete business-specific solution. The editor and renderer operate configured modules; this guide does not imply an unrestricted table designer or arbitrary SQL access.

## RecordId connects the data

The same canonical record can participate in permitted relationships, favorites and activity without a second copy of the business item. Use the supported record relationship tools to connect an asset to other records. Each connected record keeps its own permissions; a link never grants access to a hidden record. Availability of search, automation or AI also depends on that feature's configuration and permission rules.

## Use dynamic records through the API

Integrations can discover a configured module's public schema and work with its records. The public Developer API base is `/v1/apps/{saasAppId}/modules/dynamic`. Browser clients use the corresponding signed-in routes under `/api/modules/dynamic`.

| Action | Method and path after the base |
| --- | --- |
| Discover available modules | `GET` the base path |
| Read field schema and capabilities | `GET /{moduleKey}/schema` |
| List, search and page records | `GET /{moduleKey}` |
| Read one record | `GET /{moduleKey}/{recordId}` |
| Create a record | `POST /{moduleKey}` |
| Edit a record | `PUT /{moduleKey}/{recordId}` |
| Remove a record | `DELETE /{moduleKey}/{recordId}?expectedUpdatedUtc=...` |
| Set a favorite | `PUT /{moduleKey}/{recordId}/favorite` |

For example, after configuring an `assets` module and an organization text field named `c_asset_tag`, this body creates a Personal record through `POST /{moduleKey}`:

```
{
  "title": "Warehouse forklift 12",
  "isPersonal": true,
  "fields": [
    { "fieldKey": "c_asset_tag", "valueText": "FL-012" }
  ]
}
```

Read the actual schema before sending values; the example field must already exist, and any other required fields must also be supplied. For a shared record, explicitly select a permitted DataRole and, when active locations exist, an authorized location or All locations. All locations requires all-location authority; an omitted choice is not All. Personal records have no DataRole or location.

List requests support `search`, `status`, `pageNumber`, `pageSize` and `sort`. The supported list orders are `created_asc`, `created_desc`, `title_asc` and `title_desc`; a field's Sortable setting does not add an arbitrary field-sort parameter to this route. Page size is at most 100; a write accepts at most 200 field inputs, with configured limits and validation still applying.

Read current details before editing or removing and send the returned `updatedUtc` as `expectedUpdatedUtc`. A stale change is refused so an integration does not silently overwrite someone else's work. The current edit contract preserves the record's Personal/DataRole scope; do not send a new visibility choice in an ordinary update.

These are record-data operations. Builder field definitions and field policy have separate design operations under `/v1/apps/{saasAppId}/design/fields/{moduleKey}`. A record-create request does not create a module or add field definitions. Use the [current API reference](../api/interactive-api-reference.html)  and [Developer API guides](../api/index.html)  for authentication, operation scopes and the exact request contracts.

## Permissions apply everywhere

The API uses verified app, organization and user identity and the same secured services and stored procedures as the browser. Developer credentials need the appropriate API scope and an authorized tenant principal. Reads and mutations still enforce Personal ownership or current DataRole and location permissions, with separate create, edit and remove authority. Each SaaS retains its own database set.

Hidden and encrypted fields are excluded from the generic public dynamic schema. Sensitive fields require their supported secure-field controls and permission-checked reveal/edit flow; this generic field API is not a way to reveal or overwrite them.

Tip

Use Dynamic Records when the main requirement is a configurable data model. Use a specialized module when the workflow needs its own behavior, such as scheduling, billing or conversation delivery. Both can participate in the same secured RecordId system.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/dynamic-module-system.html).

---
title: "React component catalog and copy/paste kit"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/react-component-catalog.html"
reviewed_at: "2026-09-14"
authority: Official
---

# React component catalog and copy/paste kit

Copy styled or unstyled React starters for all first-class capabilities, native page modules, Universal Inbox, GoClaw, menus, shell layouts, data bindings and exact API contracts.

## In brief

- **Capabilities:** 25
- **Page renderers:** 30
- **Cataloged routes:** 419
- **Page-module gaps:** 0

This is the source-driven inventory and copy/paste kit for BuildWithHQ React pages and the tenant shell around them. It covers every documented first-class capability, core blocks, native page modules, Universal Inbox, GoClaw review work, menus, page bootstrap, data bindings, exported browser functions, HTTP routes, VB service members, and reviewed SQL procedures. The generated files live under `catalog-generator/generated/`.

[Capabilities](#capabilities) [Start a page](#start) [Menus](#menus) [Data bindings](#bindings) [Tenant shell](#shell) [Page modules](#all-modules) [All APIs](#all-apis) [Complete React source](#source)

Note

The current inventory contains 25 first-class capabilities, 32 page SDK/API surfaces, 30 bound page renderers, 304 page-module server operations, 115 additional tenant/design routes, 307 tenant API exports, 33 Design API exports, and 22 Inbox/GoClaw client methods. All 304 page-module operations resolve to reviewed stored-procedure contracts; the generated page-module gap count is 0.

## Choose native or custom presentation

| Approach | Use it when | What you own |
| --- | --- | --- |
| **Native first-class block** | You want the complete module behavior. | Page composition, menu placement, design tokens and permitted block props. BuildWithHQ owns SDK parsing, API calls, authorization-aware states and writes. |
| **Unstyled starter** | You need your own markup or design system. | Semantic presentation, accessibility and state rendering. Inject the official authenticated loader and keep its parser. |
| **Styled starter** | You want a production-shaped starting layout. | The same contract as unstyled, plus opt-in CSS. The supplied desktop catalog is left aligned at 280px / flexible / 280px. |

Important

Do not turn a React prop into an authorization decision. The server derives SaaS app, tenant account, user, DataRole and location from verified identity. Browser-supplied record IDs, page keys, filters and binding keys are query targets only.

## Every first-class capability

The capability catalog separates native page blocks, tenant-shell components, and background services. Every capability has a generated unstyled and styled explanatory React export. Those cards tell a developer what is available; they do not imitate or replace the secured native behavior.

[Connected work](#capability-connected-work) [Knowledge finder](#capability-knowledge-finder) [Universal Inbox](#capability-universal-inbox) [Checklists & Signoffs](#capability-checklists-signoffs) [GoClaw](#capability-goclaw) [AI Insights](#capability-ai-insights) [Contacts](#capability-contacts) [Work Orders](#capability-work-orders) [Reservations](#capability-reservations) [Calendar](#capability-calendar) [Files](#capability-files) [Conversations](#capability-conversations) [Company news](#capability-company-news) [Knowledge Core](#capability-knowledge-core) [Web links](#capability-web-links) [Chat rooms](#capability-chat-rooms) [Discussion Boards](#capability-discussion-boards) [Mail reader](#capability-mail-reader) [Favorites](#capability-favorites) [Notifications](#capability-notifications) [Dynamic Records](#capability-dynamic-records) [ActiveWorkplace](#capability-active-workplace) [Record relations](#capability-record-relations) [Record activity](#capability-record-activity) [Global secured search](#capability-global-search)

****Connected work** `product-solution-renderer`**

Find records you can read, explore their visible connections, and open their native pages to work on them.

| Experience | Read-only record discovery |
| --- | --- |
| Native page key | `module.connected-work` |
| React implementation | `ConnectedWorkModule` |
| API roots | `/api/modules/record-graph` |

#### What developers can build

- Search by saved record title with Search records, then use Load more records for additional results.
- Choose a result to see its visible related work. Explore follows a connected record without copying it.
- Open native record and Open record use persisted page associations. When several destinations are available, choose the page you want; no destination is guessed.
- A display-limit notice means the shown connections are bounded, not the complete relationship count. Explore a connected record to continue.
- If loading fails, Try again repeats the requested search or connection lookup under your current access.

#### Common uses

- Follow a meeting to its related work order or file.
- Find the native page for a record discovered through another module.
- Review visible relationships before opening the owning record.

**Security boundary:** Every search and connection read uses the verified user, tenant organization, and SaaS app. Personal ownership, DataRole, location, private-record, and action rules remain enforced by the secured services. A visible relationship or page link never grants access to its target.

[Open the complete Connected work implementation guide](../first-class-modules/connected-work.html)

****Knowledge finder** `product-solution-renderer`**

Search accessible Knowledge Core articles, filter publication state, preview current text, and open the native article page.

| Experience | Read-only article discovery |
| --- | --- |
| Native page key | `module.knowledge-finder` |
| React implementation | `KnowledgeFinderModule` |
| API roots | `/api/modules/knowledge-core` |

#### What developers can build

- Enter a search and choose All accessible articles, Published, Draft, or Archived in Publication state, then select Search articles.
- Use Previous article page and Next article page to browse the applied search and publication-state filter.
- Preview an article to read its current publication state, authority level, revision, summary, and article text.
- Draft and archived previews explicitly say they are unavailable as published citations. Selecting a filter never grants access to those articles.
- Open article resolves the record's persisted native page choices. If no destination is available, use the displayed unavailable-state guidance rather than guessing a route.
- Try again retries the failed search page or article preview using current permissions.

#### Common uses

- Find an operating procedure by its title or search text.
- Review an accessible draft before opening Knowledge Core.
- Check an article's current revision and publication state.

**Security boundary:** The verified user, tenant organization, SaaS app, and persisted page identity determine the current request. Knowledge Core applies its record, Personal ownership, DataRole, location, private-record, and action-specific permissions. Search terms, publication filters, menu labels, and client-supplied IDs are query targets, never authorization proof.

[Open the complete Knowledge finder implementation guide](../first-class-modules/knowledge-finder.html)

****Universal Inbox** `shell-and-page-component`**

Collects configured external email, optional support tickets, SMS, web-form submissions, and other inbound communications into one secured attention layer where unsorted work stays visible and routing rules can classify, prioritize, assign, and queue it for action.

| Experience | Inbound work & triage |
| --- | --- |
| Native page key | `core.universal-inbox` |
| React implementation | `UniversalInbox`, `UniversalInboxBell`, `UniversalInboxPageModule` |
| API roots | `/api/inbox`, `/api/inbox/items` |

#### What developers can build

- Receive configured inbound email and SMS through native Conversations and messages.
- Let an account owner enable Ticketing per inbound email address and assign stable mailbox-scoped ticket numbers.
- Use New, Open, WaitingCustomer, WaitingInternal, Snoozed, Resolved, and Closed as one controlled ticket-resolution lifecycle.
- Receive web-form submissions and other authenticated inbound source events without losing their native source record.
- Keep unmatched or unsorted items visible for human triage instead of dropping them into a hidden channel silo.
- Apply deterministic routing rules and permitted AI classification to assign queues, owners, tags, priorities, and due/SLA attention.
- Open the full native source context, prepare replies or actions, approve governed suggestions, snooze, reassign, and complete work.
- Increment ActivityVersion when new source activity arrives so stale drafts or actions cannot execute.

#### Common uses

- One intake queue for support, sales, service, operations, and customer requests.
- A technical-support mailbox with durable ticket identity and resolution state.
- Sorting unknown inbound communication before it reaches a team or person.
- Shared ownership, SLA, escalation, and GoClaw-assisted preparation across external channels.

**Security boundary:** An item is visible only when the current user can access its source record and effective queue scope. Routing never grants source access. GoClaw preparation, approval, and execution reapply the user's record/DataRole/location envelope, AI-read gate, action permission, and current ActivityVersion.

[Open the complete Universal Inbox implementation guide](../first-class-modules/universal-inbox.html)

****Checklists & Signoffs** `page-module`**

Attaches reusable, versioned checklists to authorized records and lets each item require notes, documents, or photos before the completed run enters the existing Workflow signoff path.

| Experience | Evidence-backed work acceptance |
| --- | --- |
| Native page key | `module.checklists-signoffs` |
| React implementation | `ChecklistsSignoffsModule` |
| API roots | `/api/modules/checklists-signoffs` |

#### What developers can build

- Create reusable versioned templates with ordered required or optional items.
- Attach a template snapshot to any authorized universal record.
- Track up to 1,000 ordered run items with completion actor, time, note, and revision.
- Require one or more native File documents or photos as proof for selected items.
- Calculate bounded progress and refuse submission while required work or evidence is missing.
- Submit exactly one current run to the existing Workflow and Universal Inbox approval path.
- Support rejection, editing, proof replacement, resubmission, approval, and replayable history.
- Reject stale revisions and make duplicate completion, submission, and decision requests idempotent.

#### Common uses

- Work-order inspection and closeout proof.
- Project stage-gate and quality checklists.
- Support-ticket diagnostic or escalation checkoffs.
- Safety, compliance, onboarding, handoff, and document-review signoffs.

**Security boundary:** Every list, detail, item update, evidence link/download, submission, and decision derives tenant, user, DataRole, Location, and source-record scope from server identity. Evidence links do not grant File access, and Workflow permissions—not checklist UI state—control signoff authority.

[Open the complete Checklists & Signoffs implementation guide](../first-class-modules/checklists-signoffs.html)

****GoClaw** `shell-and-page-component`**

Adds a dedicated virtual assistant to a user account that researches, summarizes, classifies, drafts, and proposes work without ever receiving more access or action authority than that user.

| Experience | Permission-bound AI assistance |
| --- | --- |
| Native page key | `module.goclaw` |
| React implementation | `GoClawApprovalQueue`, `GoClawModule` |
| API roots | `/api/goclaw/agents`, `/api/goclaw/approvals` |

#### What developers can build

- Read only records, fields, locations, and Inbox context the represented user may read—and only when AI access is also allowed.
- Research, classify, summarize, draft replies, and prepare structured next actions.
- Create suggestion batches whose evidence, risk, confidence, required permission, and inputs can be reviewed.
- Route material or customer-facing actions through configured policy or human approval before deterministic execution.
- Respect action budgets, leases, retries, stale-context fences, and idempotent execution.
- Record attribution, approval/refusal, tool/action evidence, results, failures, ratings, and correlation history.

#### Common uses

- Triage and response preparation for permitted Universal Inbox work.
- Account, case, project, support, or operations research and follow-up suggestions.
- A personal daily assistant that reduces preparation work while the user retains decision authority.

**Security boundary:** GoClaw operates on behalf of one user. Its effective access is the intersection of that user's tenant, DataRole, record, field, location, and action permissions with AI-specific CanAiReadRecords, secure-field exclusions, tool policy, quotas, approval policy, and the current source/Inbox activity version. The result can be narrower than the user's normal access, never wider.

[Open the complete GoClaw implementation guide](../first-class-modules/goclaw.html)

****AI Insights** `page-module`**

Runs permission-aware AI analysis in the background each day to create prioritized, evidence-backed insights and governed next actions from meaningful changes in authorized business records.

| Experience | Proactive daily findings |
| --- | --- |
| Native page key | `module.ai-insights` |
| React implementation | `AiInsightsModule` |
| API roots | `/api/modules/ai-insights` |

#### What developers can build

- Run a durable daily background cycle for configured insight types and source scopes.
- Steer each nightly run with the app's starter directives and the organization's own "look for" directives; the organization owner turns AI Insights on in Account admin > AI Insights.
- Read only AI-eligible records and evidence through tenant, DataRole, field, location, and CanAiReadRecords controls.
- Create structured insights with source record, type/category, title, summary, recommended action, priority, confidence, severity, evidence, model/profile provenance, and lifecycle dates.
- Use source version/context fingerprints and current-state checks to avoid repeatedly presenting stale or duplicate findings.
- Deliver each insight only to users who can currently access its source record; losing source access removes the insight from their secured feed.
- Let each user view, pin, snooze, hide, dismiss, or advance an insight without changing another user's personal feed state.
- Turn a recommended next step into a governed action that still requires the current user's action permission and configured policy or approval.

#### Common uses

- Daily account risk, opportunity, renewal, follow-up, and customer-health findings.
- Operational exceptions, overdue work, recurring issues, quality changes, and material KPI movement.
- Proactive company-knowledge, case, service, sales, support, or asset insights with evidence links.

**Security boundary:** Insight generation applies the AI-read envelope before model context is assembled. Insight visibility is inherited from the source record and rechecked at read time. Evidence, recommendations, and actions cannot reveal or operate on records, fields, locations, or tools outside the current user's permissions; material execution uses action-specific permission and policy/approval.

[Open the complete AI Insights implementation guide](../first-class-modules/ai-insights.html)

****Contacts** `page-module`**

Provides a secured contact directory with configurable contact types, search, create/detail experiences, custom fields, relationships, activity, and favorites.

| Experience | People & organizations |
| --- | --- |
| Native page key | `module.contacts` |
| React implementation | `ContactsModule` |
| API roots | `/api/modules/contacts` |

#### What developers can build

- Search and browse only the contacts visible to the current user.
- Create contacts with name, company, email, phone, and configurable type fields.
- Show secured contact detail, custom fields, related records, activity, and favorite state.
- Reuse the same contact identity across other modules instead of creating duplicate people records.

#### Common uses

- Customer and prospect directories.
- Members, vendors, partners, or project stakeholders.
- The person/company context behind conversations, events, work orders, files, and cases.

**Security boundary:** Contact lists and details apply SaaS, tenant, DataRole, location, record, and field rules. Create and edit controls appear only when secured responses grant the corresponding capability; hidden or encrypted dynamic fields are not returned.

[Open the complete Contacts implementation guide](../first-class-modules/contacts.html)

****Work Orders** `page-module`**

Tracks work requests through a secured lifecycle with number, customer, location, summary, priority, status, assignments, related records, and service evidence.

| Experience | Operational work |
| --- | --- |
| Native page key | `module.work-orders` |
| React implementation | `WorkOrdersModule` |
| API roots | `/api/modules/work-orders` |

#### What developers can build

- Search and filter work orders by text and status.
- Create work with summary, description, priority, and optional customer context.
- Move work through the supported status lifecycle with optimistic concurrency.
- Assign team members, designate primary responsibility, and expose related-record counts.
- Let the tenant choose whether Work Order payment collection is disabled, optional, required, manual, at creation, or required before completion.
- Show secured payment history and queue idempotent charges against protected, consented payment methods without exposing card or provider secrets.

#### Common uses

- Field service and maintenance dispatch.
- Facilities, asset, repair, installation, or inspection follow-up.
- Internal service requests and operational task queues that need a stronger lifecycle than a simple task.

**Security boundary:** The service limits rows by SaaS app, tenant, DataRole, and location and separately checks create, transition, assignment, and payment authority. The account owner manages payment policy and external connector references. Collection requires the existing CanBillRecords capability plus edit and record scope; customer and assignee identifiers are query/action targets, not proof of access.

[Open the complete Work Orders implementation guide](../first-class-modules/work-orders.html)

****Reservations** `page-module`**

Turns a bookable product purchase into one secured workflow: contact identity, capacity-protected reservation, protected charge, calendar event, tenant-user assignment, resource booking, and scheduled before/after-service follow-up.

| Experience | Sell, schedule & follow up |
| --- | --- |
| Native page key | `module.reservations` |
| React implementation | `ReservationsModule` |
| API roots | `/api/modules/reservations` |

#### What developers can build

- Define bookable products with duration, price/currency, party limits, concurrent capacity, buffers, hold time, and default location, resource, assignee, and follow-up timing.
- Create or safely reuse an authorized Contact and preserve the purchaser's name, email, phone, and notes.
- Create a capacity-protected Reservation and linked Calendar event, with an optional Resource booking and an active tenant user assigned to deliver the service.
- Queue the existing idempotent charge-intent pipeline using a protected payment-method reference; the API never receives card numbers, security codes, processor credentials, or raw payment tokens.
- Keep paid bookings pending and private until the charge worker reports success, then promote the reservation, event, resource, and follow-ups transactionally.
- Track Pending Payment, Requires Action, Confirmed, Checked In, Completed, Cancelled, No Show, and Payment Failed with optimistic concurrency and an audit timeline.
- Schedule separate pre-service and post-service follow-up date/time, recipient email, subject, message, delivery state, attempts, sent time, and outbound-message reference.
- Use idempotency keys to make checkout retries safe and prevent duplicate contacts, charges, calendar events, and reservations.
- Let the tenant account owner choose disabled, optional, or required collection; creation, manual, or completion timing; full or deposit collection; partial-payment rules; currency; minimum charge; and paid-before-completion enforcement.
- Give users with the existing billing capability a secured balance, payment history, charge history, and protected charge action for the reservation record.

#### Common uses

- Paid consultations and professional-service appointments.
- Tours, classes, lessons, events, and capacity-limited sessions.
- Installations, inspections, salon/wellness visits, rentals, and service calls.
- Free appointments that still need contact, calendar, assignment, capacity, and follow-up.

**Security boundary:** List/detail access is inherited from secured universal Records. Product management and mutations require current DataRole capability. Locations and contact targets are revalidated in the user's scope; assignees must be active users assigned to the same app and selected location. Product capacity and opt-in consultation/appointment assignee exclusivity are rechecked transactionally on purchase, reschedule, confirmation, and delayed payment success. Existing shared-capacity products remain non-exclusive by default. Identity comes from verified server context. The tenant account owner controls payment policy and connector references; collection requires the existing CanBillRecords capability plus record scope. Raw card data and provider credentials are never accepted or persisted by Reservations.

[Open the complete Reservations implementation guide](../first-class-modules/reservations.html)

****Calendar** `page-module`**

Provides secured month/agenda scheduling for events, attendees, resources, reminders, locations, private events, custom fields, relationships, activity, and favorites.

| Experience | Time & scheduling |
| --- | --- |
| Native page key | `module.calendar` |
| React implementation | `CalendarModule` |
| API roots | `/api/modules/calendar` |

#### What developers can build

- Browse monthly event ranges and search visible events.
- Create timed or all-day events with location, reminder, color, and privacy settings.
- Show attendee responses, resource bookings, custom fields, related records, and activity.
- Favorite important events and connect them to customers, projects, work orders, or cases.

#### Common uses

- Customer meetings and project milestones.
- Technician visits, inspections, shifts, or resource schedules.
- Renewal dates, campaign launches, approval deadlines, and case hearings.

**Security boundary:** Calendar queries enforce tenant, DataRole, location, and private-event rules. Attendees and related records are independently secured, and event creation/editing requires the corresponding server permission.

[Open the complete Calendar implementation guide](../first-class-modules/calendar.html)

****Files** `page-module`**

Provides private file upload, download, metadata, tags, record attachments, comments, locks, custom fields, relationships, activity, and favorites without exposing storage coordinates.

| Experience | Documents & evidence |
| --- | --- |
| Native page key | `module.files` |
| React implementation | `FilesModule` |
| API roots | `/api/modules/files` |

#### What developers can build

- Search and filter secured file metadata by name and content type.
- Upload, describe, tag, edit, and privately download authorized files.
- Keep personal files only you can see, up to the per-person limit the organization owner sets within the app's ceiling.
- Attach one file to multiple permitted records without duplicating the binary.
- Show comments, locks, custom fields, relations, activity, and favorite state.

#### Common uses

- Customer and project documents.
- Inspection photos, work-order evidence, manuals, and invoices.
- Case evidence, knowledge source files, and signed approvals.

**Security boundary:** Download and upload flow through authenticated backend endpoints. The browser never receives provider credentials, tenant database identity, storage paths, or unrestricted object-store locations; attachment targets are reauthorized independently.

[Open the complete Files implementation guide](../first-class-modules/files.html)

****Conversations** `page-module`**

Provides native channel threads with participants, messages, status, priority, internal notes, outbound replies, related context, activity, dynamic fields, and favorites.

| Experience | Customer & team communication |
| --- | --- |
| Native page key | `module.conversations` |
| React implementation | `ConversationsModule` |
| API roots | `/api/modules/conversations` |

#### What developers can build

- Search and filter conversation threads by status.
- Create internal conversations and manage subject, priority, and lifecycle.
- Read escaped message history and post internal notes or permitted outbound replies.
- Expose unread/favorite state, dynamic fields, related records, and activity.

#### Common uses

- Customer support and success communication.
- Project, sales, case, and operations correspondence.
- The native thread behind Universal Inbox triage and governed AI suggestions.

**Security boundary:** Conversation, message, channel, DataRole, and location access is enforced server-side. Outbound capability and edit rights are explicit; provider credentials and direct channel endpoints never reach the browser.

[Open the complete Conversations implementation guide](../first-class-modules/conversations.html)

****Company news** `page-module`**

Publishes searchable internal announcements with draft, scheduled, published, and expired visibility, author controls, custom fields, relationships, activity, and favorites.

| Experience | Announcements |
| --- | --- |
| Native page key | `module.company-news` |
| React implementation | `CompanyNewsModule` |
| API roots | `/api/modules/company-news` |

#### What developers can build

- Search visible announcements and open their secured detail.
- Author and edit announcements only when the response grants edit permission.
- Control draft, scheduled, published, and expired visibility.
- Connect announcements to records, activity, custom fields, and personal favorites.

#### Common uses

- Internal news and release announcements.
- Location-specific closures, safety notices, or operating updates.
- Policy and program communications linked to supporting records or files.

**Security boundary:** Publication state, SaaS, tenant, DataRole, and location are evaluated by secured reads. Announcement bodies render as escaped text, and authoring controls depend on server-reported permission.

[Open the complete Company news implementation guide](../first-class-modules/company-news.html)

****Knowledge Core** `page-module`**

Turns tenant knowledge into owned, revisioned, reviewable records that connect to business context, answer questions, support permission-aware AI/RAG, and learn safely from resolved support work.

| Experience | Maintained, cited knowledge |
| --- | --- |
| Native page key | `module.knowledge-articles` |
| React implementation | `KnowledgeArticlesModule` |
| API roots | `/api/modules/knowledge-articles`, `/api/modules/knowledge-core` |

#### What developers can build

- Create Draft knowledge and publish or archive it through permission-checked lifecycle actions.
- Preserve immutable revisions, publication history, authority, AI eligibility, and optimistic-concurrency evidence.
- Assign one primary accountable owner to a user or DataRole and schedule recurring review work.
- Relate knowledge to any authorized RecordId and retrieve bounded contextual knowledge without copying the business record.
- Capture unanswered questions, repeated occurrences, usage, feedback, and secured knowledge-gap signals.
- Register only Published, AI-eligible revisions for secured semantic/multimodal retrieval with exact citations.
- Bring current support knowledge into fenced GoClaw Inbox context and turn resolved cases into sanitized Draft candidates.

#### Common uses

- Owned product documentation, policies, procedures, FAQs, and employee help.
- Customer-safe help centers and support answers with exact current citations.
- Contextual playbooks linked to customers, products, cases, work orders, files, and conversations.
- Permission-aware AI/RAG sources whose authority and freshness must be inspectable.
- A controlled support learning loop that turns reusable resolutions into reviewable Drafts.

**Security boundary:** Every list, item, relation, review, question, feedback, support-context, and AI path derives the SaaS app, tenant, user, DataRole, location, record, field, and permission scope from verified server identity. CanAiReadRecords is required before AI context. Publication, ownership, review, support learning, and archive actions have separate permission checks; customer-visible context excludes internal-only sources.

[Open the complete Knowledge Core implementation guide](../first-class-modules/knowledge-core.html)

****Web links** `page-module`**

Maintains searchable, categorized, location-aware external links with descriptions, custom fields, relationships, activity, and favorites.

| Experience | Curated external resources |
| --- | --- |
| Native page key | `module.web-links` |
| React implementation | `WebLinksModule` |
| API roots | `/api/modules/web-links` |

#### What developers can build

- Search links and filter them by category.
- Create and edit title, URL, description, category, and custom fields.
- Open only contract-validated HTTP or HTTPS destinations in an isolated browsing context.
- Relate and favorite links while preserving location-aware access.

#### Common uses

- Team resource directories.
- Customer/vendor portals and external documentation.
- Research links connected to cases, projects, accounts, or knowledge.

**Security boundary:** The server accepts strict host-based HTTP(S) URLs without embedded credentials. The runtime opens destinations with an isolated external context and applies normal tenant, DataRole, and location checks to the link record.

[Open the complete Web links implementation guide](../first-class-modules/web-links.html)

****Chat rooms** `page-module`**

Provides secured team rooms with messages, unread state, membership, room administration, mute settings, reactions, archives, custom fields, relations, activity, and favorites.

| Experience | Members-only team discussion |
| --- | --- |
| Native page key | `module.chat-rooms` |
| React implementation | `ChatRoomsModule` |
| API roots | `/api/modules/chat-rooms` |

#### What developers can build

- Search active or archived rooms and see unread counts.
- Create/edit rooms, post messages, and react with bounded reaction types.
- Manage members, room administrators, mute state, and archive state when authorized.
- Show location, dynamic fields, related records, activity, and favorites.

#### Common uses

- Project or operations team chat.
- Location, department, incident, or customer team rooms.
- Informal collaboration adjacent to records that retain the formal work state.

**Security boundary:** Rooms are shared-only: explicitly select one eligible DataRole and an authorized location or All when available. Room and message reads require current membership plus DataRole/location access, including Graph, Activity, Favorites and direct record links. Native Chat Rooms search remains available; general and AI search exclude chat content. Saves recheck current authority. Member administration, room edits and archiving require the appropriate room capability; members can post and edit their own messages without gaining room-administration rights.

[Open the complete Chat rooms implementation guide](../first-class-modules/chat-rooms.html)

****Discussion Boards** `page-module`**

Provides boards, topics, threaded posts, replies, pin/lock moderation, archives, owned-post editing, custom fields, relations, activity, and favorites.

| Experience | Structured community discussion |
| --- | --- |
| Native page key | `module.discussion-boards` |
| React implementation | `DiscussionBoardsModule` |
| API roots | `/api/modules/discussion-boards` |

#### What developers can build

- Search active or archived boards and browse topic/post counts.
- Create boards and topics, reply to topics, and edit owned or otherwise authorized content.
- Pin or lock topics and archive boards with the required moderation capability.
- Favorite boards/topics and show secured relations, activity, location, and dynamic fields.

#### Common uses

- Customer or partner communities.
- Internal Q&A, proposals, and long-running technical discussions.
- Program, project, or policy forums that benefit from topic-level history.

**Security boundary:** Board, topic, and post operations enforce tenant, DataRole, location, ownership, and moderation rules. Locked topics refuse ordinary replies, and edit controls reflect secured response capabilities.

[Open the complete Discussion Boards implementation guide](../first-class-modules/discussion-boards.html)

****Mail reader** `page-module`**

Provides a read-focused view across authorized personal/shared mail accounts with search, unread filtering, plain-text message detail, read state, relations, activity, dynamic fields, and favorites.

| Experience | Secured inbound mail |
| --- | --- |
| Native page key | `module.mail-reader` |
| React implementation | `MailReaderModule` |
| API roots | `/api/modules/mail-reader` |

#### What developers can build

- Select authorized personal or shared accounts and view unread counts.
- Search messages and filter unread mail.
- Read safe plain-text headers, previews, and bodies; raw HTML is not rendered.
- Mark permitted messages read/unread and connect them to favorites, relations, activity, and custom fields.

#### Common uses

- Shared operations or support mailbox review.
- Account/project email research linked to business records.
- Read-focused compliance or case correspondence views.

**Security boundary:** Account ownership/shared access, SaaS, tenant, DataRole, and location are enforced server-side. Incoming-server settings, credential references, raw HTML, and private provider details are excluded from browser responses.

[Open the complete Mail reader implementation guide](../first-class-modules/mail-reader.html)

****Favorites** `page-module`**

Gives each user a secured cross-module list of saved records with search, module filters, pinning, change tracking, related context, activity, and dynamic fields.

| Experience | Personal workspace |
| --- | --- |
| Native page key | `module.favorites` |
| React implementation | `FavoritesModule` |
| API roots | `/api/modules/favorites` |

#### What developers can build

- Search personal favorites and filter by source module.
- Pin, reorder, remove, and optionally track changes on saved records.
- Show current secured status, location, relations, activity, and dynamic fields.
- Collapse duplicate favorite targets into a coherent personal workspace.

#### Common uses

- Pinned customers, projects, cases, files, or articles.
- A personal watch list for records whose changes matter.
- Cross-module navigation for frequently used work.

**Security boundary:** Only the current user's favorite rows are returned. Target records, related records, fields, activity, and location are independently secured, so a favorite never preserves access after permission is removed.

[Open the complete Favorites implementation guide](../first-class-modules/favorites.html)

****Notifications** `page-module`**

Provides recipient-scoped alerts with unread filtering, detail, dismissal, source-record context, relations, activity, and source favorites.

| Experience | Personal alerts |
| --- | --- |
| Native page key | `module.notifications` |
| React implementation | `NotificationsModule` |
| API roots | `/api/modules/notifications` |

#### What developers can build

- Search current-recipient notifications and filter unread items.
- Open bounded detail and mark or dismiss notification state.
- Show a permitted source title, location, relations, and activity.
- Favorite an authorized source record directly from the notification.

#### Common uses

- Assignment, mention, publication, and status-change alerts.
- Workflow completion, failure, or approval attention.
- Personal reminders that link back to the canonical source record.

**Security boundary:** Only rows for the current recipient and app/account are returned. Linked source metadata appears only after its normal DataRole and location checks; the browser cannot submit recipient or permission authority.

[Open the complete Notifications implementation guide](../first-class-modules/notifications.html)

****Dynamic Records** `page-module`**

Renders tenant-owned custom modules from their validated field schema with secured list, search, create, detail, edit, status, relations, activity, and favorites.

| Experience | Builder-defined data |
| --- | --- |
| Native page key | `module.dynamic-records` |
| React implementation | `DynamicModulesModule` |
| API roots | `/api/modules/dynamic` |

#### What developers can build

- Load only a validated tenant-owned module key supplied by the page contract.
- Render the public field schema while excluding hidden and encrypted fields.
- Search, create, inspect, edit, and change status according to existing permissions.
- Participate in relations, activity, location scope, and favorites through universal RecordId.

#### Common uses

- Industry-specific business objects.
- Rapidly modeled MVP records and internal tools.
- Reusable template-defined objects that do not need a specialized native experience.

**Security boundary:** The server accepts only tenant-owned custom module keys and refuses generic access to built-in modules. Field schema, DataRole, field, record, and location rules determine which values and controls are returned.

[Open the complete Dynamic Records implementation guide](../first-class-modules/dynamic-records.html)

****ActiveWorkplace** `page-module`**

Pins any permitted Record into a collaborative workplace over its secured recursive relationship graph, with people, GoClaws, workflows, Record Pulse, Inbox attention, activity, and read-only Graph Playback.

| Experience | Recursive work coordination |
| --- | --- |
| Native page key | `module.active-workplace` |
| React implementation | `ActiveWorkplaceModule` |
| API roots | `/api/modules/active-workplace` |

#### What developers can build

- Pin any currently permitted Record once as the workplace root.
- Capture a cycle-safe, bounded Active Graph over existing typed Record Relations.
- Coordinate named users, GoClaw assistants, and published workflows with explicit responsibilities.
- Track Active, Waiting, At Risk, Stale, Dormant, and Resolved Record Pulse states.
- Create or touch one Universal Inbox attention item when a workplace becomes At Risk or Stale.
- Record meaningful comments, participant changes, status transitions, related-record changes, and graph refreshes in an immutable activity stream.
- Reconstruct retained workplace, participant, graph, and activity state through unmistakably read-only Graph Playback while applying current permissions.
- Accept bounded builder defaults for root modules, graph depth/nodes, stale timing, participant types, GoClaw watchers, comments, and playback.

#### Common uses

- Complex customer, case, opportunity, project, asset, incident, contract, or collections coordination.
- A Wave-like shared work surface around connected records without copying those records.
- Cross-team handoffs where responsibilities, inactivity, dependencies, and history must stay visible.
- GoClaw monitoring and workflow participation under the same permissions and approvals as the rest of the app.

**Security boundary:** The server derives app, account, user, DataRole, and locations. Root creation requires current read/edit access; each displayed graph node is reauthorized; GoClaw assignment requires independent AI-read access; and playback applies current authorization before returning any retained identity or event. Direct table access is denied to runtime and Pulse-worker roles.

[Open the complete ActiveWorkplace implementation guide](../first-class-modules/active-workplace.html)

****Record relations** `page-module`**

Explores authorized records as a bounded relationship graph and supports typed relation creation/removal only when both endpoints are editable.

| Experience | Connected context |
| --- | --- |
| Native page key | `module.record-graph` |
| React implementation | `RecordGraphModule` |
| API roots | `/api/modules/record-graph` |

#### What developers can build

- Search visible seed records across modules.
- Traverse secured relationships through bounded depth levels.
- Show nodes, typed edges, module, location, status, activity counts, and favorites.
- Add or remove a typed relation only when both record endpoints and the relation operation are authorized.

#### Common uses

- Customer/account 360-degree context.
- Case, project, asset, and work dependency exploration.
- Impact analysis and relationship-first CRM experiences.

**Security boundary:** Every traversed node is independently checked for SaaS, tenant, DataRole, record, and location visibility. Inaccessible nodes and edges are omitted, and mutation requires edit authority on both endpoints.

[Open the complete Record relations implementation guide](../first-class-modules/record-relations.html)

****Record activity** `page-module`**

Shows a paged, filterable, chronological activity timeline for an authorized record with actor, event type/state, date range, relations, and favorite state.

| Experience | Timeline & history |
| --- | --- |
| Native page key | `module.record-activity` |
| React implementation | `RecordActivityModule` |
| API roots | `/api/modules/record-activity` |

#### What developers can build

- Search visible records across modules and select a record timeline.
- Filter activity by event type and date range.
- Group events chronologically with summary, actor, state, and occurrence time.
- Page bounded history and show secured relation/favorite context.

#### Common uses

- Customer, project, work-order, case, and asset timelines.
- Operational handoffs and investigation context.
- A user-facing history adjacent to formal compliance/audit evidence.

**Security boundary:** The selected record must pass normal scope checks, and only safe activity summaries/metadata are rendered. Private event detail payloads stay outside the browser surface.

[Open the complete Record activity implementation guide](../first-class-modules/record-activity.html)

****Global secured search** `page-module`**

Searches permitted records across modules and also uses permission-filtered vector retrieval to find meaningfully related information in indexed uploads, PDFs, images, screenshots, tables, diagrams, and text.

| Experience | Cross-module discovery |
| --- | --- |
| Native page key | `module.global-search` |
| React implementation | `GlobalSearchModule` |
| API roots | `/api/modules/global-search` |

#### What developers can build

- Run bounded text search across authorized modules and records.
- Search eligible indexed uploads, PDFs, images, screenshots, tables, diagrams, and extracted text in a shared vector space.
- Find conceptually related information even when the source uses different words from the query.
- Retrieve the original text, page, image, and source identity so results can retain evidence and citations.
- Filter by module and page through stable result envelopes.
- Show safe matched-field snippets plus module, status, location, relation, activity, and update context.
- Add or remove favorites without leaving the result list.

#### Common uses

- App-wide command and search experiences.
- Finding a record when its owning module is unknown.
- Discovering related material across records and uploaded documents.
- Finding a PDF page, image, screenshot, chart, table, or diagram from a natural-language description.
- Cross-module navigation in relationship-heavy applications.

**Security boundary:** The server applies SaaS, tenant, CanAiReadRecords, DataRole, location, record, field, and AI-eligibility rules before vector candidates or visual evidence can be returned. Unindexed, deleted, AI-excluded, or otherwise unauthorized content is absent from results. Relevance never grants access, and counts, snippets, citations, and related context must not reveal inaccessible records or fields.

[Open the complete Global secured search implementation guide](../first-class-modules/global-search.html)

## Styled preview

**Modules**
- Universal Inbox
- Contacts
- Files
- Work Orders

First-class module

### Universal Inbox

**SUP-000123**
Waiting for customer

**Website request**
New and unassigned

**Bounded data path**
1. Authenticated API
2. Typed service
3. Reviewed procedure
4. Scoped JSON

The unstyled exports contain the same landmarks, labels, lists, tables, loading state, empty state and error state without any CSS dependency.

## Start a complete page

The safest custom page starts with the official runtime bootstrap and renderer. The browser supplies only the page key. The server returns the applicable shell, menu, component contracts and authorized page document.

```

import { useEffect, useState, type ReactNode } from "react";
import type { RuntimeBootstrap } from "@buildwithhq/page-runtime";

export interface RuntimePageStarterProps {
  readonly pageKey: string;
  readonly loadBootstrap: (pageKey: string) => Promise<RuntimeBootstrap>;
  readonly renderBootstrap: (bootstrap: RuntimeBootstrap) => ReactNode;
  readonly styled?: boolean;
}

export const RuntimePageStarter = ({ pageKey, loadBootstrap, renderBootstrap, styled = false }: RuntimePageStarterProps) => {
  const [bootstrap, setBootstrap] = useState<RuntimeBootstrap | null>(null);
  const [error, setError] = useState<string | null>(null);
  useEffect(() => {
    let active = true;
    setBootstrap(null); setError(null);
    void loadBootstrap(pageKey).then((value) => { if (active) setBootstrap(value); })
      .catch((failure: unknown) => { if (active) setError(failure instanceof Error ? failure.message : "Page unavailable."); });
    return () => { active = false; };
  }, [loadBootstrap, pageKey]);
  return <main className={styled ? "bwhq-runtime-page" : undefined}>
    {!bootstrap && !error && <p role="status">Loading page…</p>}
    {error && <p role="alert">{error}</p>}
    {bootstrap && renderBootstrap(bootstrap)}
  </main>;
};

/* In apps/tenant-runtime, wire this to loadRuntimeBootstrap and RuntimePageRenderer.
   Authentication is already held by the official API client; do not add SaaSAppId,
   AppAccountId, UserId, DataRole or database-name props to this component. */
```

Tip

Inside apps/tenant-runtime, pass loadRuntimeBootstrap as loadBootstrap and render with RuntimePageRenderer. Keep the existing in-memory authenticated client; do not create a second token store.

## Core page blocks

| Component key | Purpose | Registry source |
| --- | --- | --- |
| `core.button` | Button | `packages/ui/src/index.tsx` |
| `core.container` | Container | `packages/ui/src/index.tsx` |
| `core.data-grid` | Data Grid | `packages/ui/src/index.tsx` |
| `core.form` | Form | `packages/ui/src/index.tsx` |
| `core.record-list` | Record List | `packages/ui/src/index.tsx` |
| `core.text` | Text | `packages/ui/src/index.tsx` |

Every block requires stable `_id`, `_type`, `props`, and `children`. The current runtime accepts up to 5,000 blocks and 60 levels of depth. A block type must have a returned component contract or it fails closed as unavailable.

## Menus and user types

A menu item is a Page, Group, Module, or External target. Page items point to shared `pageKey` values; they do not copy page content. User Types choose the intended menu and dashboard, while DataRoles and Locations independently authorize the resulting data.

```
const menu = [
  { id: "work", label: "Work", targetType: "Group", sortOrder: 10 },
  { id: "inbox", parentId: "work", label: "Inbox", targetType: "Page", pageKey: "inbox", sortOrder: 10 },
  { id: "contacts", parentId: "work", label: "Contacts", targetType: "Page", pageKey: "contacts", sortOrder: 20 },
] satisfies readonly BuildWithHQMenuItem[];

<BuildWithHQMenu
  items={menu}
  activePageKey={pageKey}
  resolvePageHref={(key) => `/?page=${encodeURIComponent(key)}`}
  styled
/>
```

**Copy the complete styled/unstyled menu component**

```

import type { ReactNode } from "react";

export interface BuildWithHQMenuItem {
  readonly id: string;
  readonly parentId?: string | null;
  readonly label: string;
  readonly iconKey?: string | null;
  readonly targetType: "Page" | "Group" | "Module" | "External";
  readonly pageKey?: string | null;
  readonly url?: string | null;
  readonly sortOrder: number;
}

export interface BuildWithHQMenuProps {
  readonly items: readonly BuildWithHQMenuItem[];
  readonly activePageKey?: string;
  readonly resolvePageHref: (pageKey: string) => string;
  readonly icon?: (iconKey: string) => ReactNode;
  readonly styled?: boolean;
}

const safeExternalUrl = (value: string | null | undefined): string | undefined => {
  if (!value || value.length > 2000) return undefined;
  try {
    const url = new URL(value);
    return url.protocol === "https:" && !url.username && !url.password ? url.toString() : undefined;
  } catch { return undefined; }
};

export const BuildWithHQMenu = ({ items, activePageKey, resolvePageHref, icon, styled = false }: BuildWithHQMenuProps) => {
  const roots = items.filter((item) => !item.parentId).sort((left, right) => left.sortOrder - right.sortOrder);
  const renderItem = (item: BuildWithHQMenuItem): ReactNode => {
    const children = items.filter((candidate) => candidate.parentId === item.id).sort((left, right) => left.sortOrder - right.sortOrder);
    if (item.targetType === "Group") return <li key={item.id}><span>{item.iconKey && icon?.(item.iconKey)}{item.label}</span>{children.length > 0 && <ul>{children.map(renderItem)}</ul>}</li>;
    const href = item.targetType === "Page" && item.pageKey ? resolvePageHref(item.pageKey)
      : item.targetType === "External" ? safeExternalUrl(item.url) : undefined;
    return <li key={item.id}>{href ? <a href={href} aria-current={item.pageKey === activePageKey ? "page" : undefined}>{item.iconKey && icon?.(item.iconKey)}{item.label}</a> : <span aria-disabled="true">{item.label}</span>}</li>;
  };
  return <nav aria-label="Application" className={styled ? "bwhq-app-menu" : undefined}><ul>{roots.map(renderItem)}</ul></nav>;
};
```

## Tenant workspace and shell components

The page renderer is only the center stage. Universal Inbox, the Inbox bell, GoClaw approval review, Assets, document metadata and the owner-only Design studio are shell surfaces in the current application. The generated workspace shell keeps the menu left-aligned, gives the middle column all remaining width, and reserves an optional 280px context rail.

| Component | Import/source | Current use | Props observed in App |
| --- | --- | --- | --- |
| `BuildWithHQIcon` | `@buildwithhq/ui` | `apps/tenant-runtime/src/App.tsx:972` | `name`, `size` |
| `DeveloperDebugDrawer` | `./DeveloperDebugDrawer` | `apps/tenant-runtime/src/App.tsx:849` | `key`, `pageKey`, `saasAppId` |
| `DeveloperDebugHistory` | `./DeveloperDebugHistory` | `apps/tenant-runtime/src/App.tsx:990` | `saasAppId` |
| `GoClawApprovalQueue` | `@buildwithhq/universal-inbox` | `apps/tenant-runtime/src/App.tsx:861` | `client`, `onClose`, `onOpenInbox` |
| `InboxRecordSourceLink` | `./UniversalInboxPageModule` | `apps/tenant-runtime/src/App.tsx:883` | `detail` |
| `NativeRecordNavigationProvider` | `./NativeRecordLink` | `apps/tenant-runtime/src/App.tsx:880` | `key` |
| `PuckPageDesignerDialog` | `./PuckPageDesignerDialog` | `apps/tenant-runtime/src/App.tsx:922` | `components`, `onClose`, `onSaved`, `page` |
| `RecordDeletionHistory` | `./RecordDeletionHistory` | `apps/tenant-runtime/src/App.tsx:950` | `key`, `onClose`, `onRestored` |
| `RecordFavoriteStar` | `./FavoriteStar` | `apps/tenant-runtime/src/App.tsx:882` | `recordId` |
| `RuntimeAssetManager` | `./RuntimeAssetManager` | `apps/tenant-runtime/src/App.tsx:891` | `onClose` |
| `RuntimeDocumentMetadata` | `./RuntimeDocumentMetadata` | `apps/tenant-runtime/src/App.tsx:800` | `appName`, `page` |
| `RuntimePageRenderer` | `./PageRenderer` | `apps/tenant-runtime/src/App.tsx:1014` | `components`, `page` |
| `RuntimeRenderBoundary` | `./RuntimeRenderBoundary` | `apps/tenant-runtime/src/App.tsx:1008` | `componentKey`, `pageKey`, `resetKey` |
| `SaasDesignStudio` | `./SaasDesignStudio` | `apps/tenant-runtime/src/App.tsx:899` | `components`, `onClose`, `onPublished`, `saasAppId` |
| `TenantAccountAdmin` | `./TenantAccountAdmin` | `apps/tenant-runtime/src/App.tsx:991` | `actor`, `key`, `onClose`, `onNavigate`, `onOpenPage`, `section` |
| `TenantAccountSecurityDialog` | `./TenantAccountSecurityDialog` | `apps/tenant-runtime/src/App.tsx:855` | `onClose` |
| `TenantBrandMark` | `./TenantBrandMark` | `apps/tenant-runtime/src/App.tsx:1046` | `brand` |
| `TenantCustomFieldsWorkspace` | `./TenantCustomFieldsWorkspace` | `apps/tenant-runtime/src/App.tsx:943` | `components`, `currentPageKey`, `onClose`, `pages` |
| `TenantInvitationAcceptance` | `./TenantInvitationAcceptance` | `apps/tenant-runtime/src/App.tsx:1031` | `onAccepted`, `token` |
| `TenantOwnershipInvitation` | `./TenantOwnershipInvitation` | `apps/tenant-runtime/src/App.tsx:828` | `key`, `mode`, `onAccepted`, `onClose`, `onOpen`, `userId` |
| `UniversalInbox` | `@buildwithhq/universal-inbox` | `apps/tenant-runtime/src/App.tsx:881` | `client`, `initialInboxItemId`, `key`, `renderFavorite`, `renderSource` |
| `UniversalInboxBell` | `@buildwithhq/universal-inbox` | `apps/tenant-runtime/src/App.tsx:840` | `client`, `onOpenInbox` |

**Copy the styled/unstyled workspace shell**

```

import type { ReactNode } from "react";

export interface TenantWorkspaceShellProps {
  readonly applicationName: string;
  readonly pageTitle: string;
  readonly menu: ReactNode;
  readonly children: ReactNode;
  readonly headerActions?: ReactNode;
  readonly contextPanel?: ReactNode;
  readonly styled?: boolean;
}

const TenantWorkspaceShellBody = ({ applicationName, pageTitle, menu, children, headerActions, contextPanel, styled = false }: TenantWorkspaceShellProps) => (
  <div className={styled ? "bwhq-workspace" : undefined}>
    <header className={styled ? "bwhq-workspace__header" : undefined}>
      <div><p>{applicationName}</p><h1>{pageTitle}</h1></div>
      {headerActions && <div aria-label="Page actions">{headerActions}</div>}
    </header>
    <div className={styled ? "bwhq-workspace__columns" : undefined}>
      <aside aria-label="Application menu" className={styled ? "bwhq-workspace__menu" : undefined}>{menu}</aside>
      <main className={styled ? "bwhq-workspace__main" : undefined}>{children}</main>
      {contextPanel && <aside aria-label="Page context" className={styled ? "bwhq-workspace__context" : undefined}>{contextPanel}</aside>}
    </div>
  </div>
);

export const UnstyledTenantWorkspaceShell = (props: Omit<TenantWorkspaceShellProps, "styled">) =>
  <TenantWorkspaceShellBody {...props} styled={false} />;

export const StyledTenantWorkspaceShell = (props: Omit<TenantWorkspaceShellProps, "styled">) =>
  <TenantWorkspaceShellBody {...props} styled />;
```

**Copy Universal Inbox, support-ticket and GoClaw starters**

```

import { useEffect, useState } from "react";

export interface InboxQueueItem {
  readonly inboxItemId: string;
  readonly source: { readonly sourceType: string };
  readonly subject?: string | null;
  readonly previewText?: string | null;
  readonly status: string;
  readonly ticket?: { readonly key?: string | null } | null;
}
export interface UniversalInboxClient {
  list(request: { readonly ticketingOnly?: boolean; readonly assignedToMe?: boolean; readonly topN: number }, signal?: AbortSignal): Promise<readonly InboxQueueItem[]>;
}
export interface ApprovalQueueItem {
  readonly suggestionBatchId: string;
  readonly subject?: string | null;
  readonly summary?: string | null;
  readonly sourceType?: string | null;
  readonly batchStatus: string;
  readonly isStale: boolean;
}
export interface ApprovalQueueClient {
  list(top: number, signal?: AbortSignal): Promise<readonly ApprovalQueueItem[]>;
}

interface InboxStarterProps {
  readonly client: UniversalInboxClient;
  readonly ticketingOnly?: boolean;
  readonly assignedToMe?: boolean;
  readonly onOpen?: (inboxItemId: string) => void;
  readonly styled?: boolean;
}

export const HeadlessInboxQueueStarter = ({ client, ticketingOnly, assignedToMe, onOpen, styled = false }: InboxStarterProps) => {
  const [items, setItems] = useState<readonly InboxQueueItem[]>([]);
  const [error, setError] = useState<string>();
  const [loading, setLoading] = useState(true);
  useEffect(() => {
    const controller = new AbortController();
    setLoading(true); setError(undefined);
    void client.list({ ticketingOnly, assignedToMe, topN: 100 }, controller.signal)
      .then(setItems)
      .catch((failure: unknown) => { if (!controller.signal.aborted) setError(failure instanceof Error ? failure.message : "Inbox unavailable."); })
      .finally(() => { if (!controller.signal.aborted) setLoading(false); });
    return () => controller.abort();
  }, [assignedToMe, client, ticketingOnly]);
  return <section aria-busy={loading} className={styled ? "bwhq-headless-list" : undefined}>
    <h2>{ticketingOnly ? "Support tickets" : "Universal Inbox"}</h2>
    {loading && <p role="status">Loading inbox…</p>}
    {error && <p role="alert">{error}</p>}
    {!loading && !error && items.length === 0 && <p>No visible work.</p>}
    <ul>{items.map((item) => <li key={item.inboxItemId}><button type="button" onClick={() => onOpen?.(item.inboxItemId)}><strong>{item.ticket?.key ? item.ticket.key + " · " : ""}{item.subject || item.source.sourceType}</strong><span>{item.status} · {item.previewText || "No preview"}</span></button></li>)}</ul>
  </section>;
};

interface ApprovalStarterProps {
  readonly client: ApprovalQueueClient;
  readonly onOpen?: (item: ApprovalQueueItem) => void;
  readonly styled?: boolean;
}

export const HeadlessApprovalQueueStarter = ({ client, onOpen, styled = false }: ApprovalStarterProps) => {
  const [items, setItems] = useState<readonly ApprovalQueueItem[]>([]);
  const [error, setError] = useState<string>();
  useEffect(() => {
    const controller = new AbortController();
    void client.list(100, controller.signal).then(setItems)
      .catch((failure: unknown) => { if (!controller.signal.aborted) setError(failure instanceof Error ? failure.message : "Approval queue unavailable."); });
    return () => controller.abort();
  }, [client]);
  return <section className={styled ? "bwhq-headless-list" : undefined}>
    <h2>GoClaw approval work</h2>{error && <p role="alert">{error}</p>}
    <ul>{items.map((item) => <li key={item.suggestionBatchId}><button type="button" onClick={() => onOpen?.(item)}><strong>{item.subject || item.summary || item.sourceType}</strong><span>{item.batchStatus}{item.isStale ? " · stale" : ""}</span></button></li>)}</ul>
  </section>;
};

/* Self-contained starter aliases: no unpublished product package is required. */
export const BareNativeUniversalInbox = (props: { readonly client: UniversalInboxClient; readonly initialInboxItemId?: string }) =>
  <HeadlessInboxQueueStarter client={props.client} />;
export const FramedNativeUniversalInbox = (props: { readonly client: UniversalInboxClient; readonly initialInboxItemId?: string }) =>
  <div className="bwhq-native-frame"><HeadlessInboxQueueStarter client={props.client} styled /></div>;
export const BareNativeGoClawApprovalQueue = (props: { readonly client: ApprovalQueueClient }) =>
  <HeadlessApprovalQueueStarter client={props.client} />;
export const FramedNativeGoClawApprovalQueue = (props: { readonly client: ApprovalQueueClient }) =>
  <div className="bwhq-native-frame"><HeadlessApprovalQueueStarter client={props.client} styled /></div>;
```

Note

The native Universal Inbox and GoClaw components intentionally import their production CSS. A “bare native” wrapper adds no frame but does not remove that CSS. The headless list exports are presentation starters only; use the native component for the complete ticket, human-state, workflow and approval lifecycle unless you deliberately implement every needed typed client action.

## Custom data bindings

A binding key resolves through `/api/runtime/data/{bindingKey}` and `sp_ResolveDataBindingByKey` to an approved `sp_ds_*` operation. The runtime derives identity, validates the configured JSON root, and caps the result. It never accepts ad-hoc SQL, a connection string, credentials, or a browser-selected tenant database.

**Copy the complete styled/unstyled data list**

```

import { useEffect, useState, type ReactNode } from "react";

export type JsonValue = string | number | boolean | null | JsonValue[] | { readonly [key: string]: JsonValue };
export type DataBindingLoader = (bindingKey: string, signal: AbortSignal) => Promise<{ readonly data: JsonValue }>;

export interface DataBoundListProps<T> {
  readonly bindingKey: string;
  readonly loadBinding: DataBindingLoader;
  readonly selectItems: (data: JsonValue) => readonly T[];
  readonly itemKey: (item: T) => string;
  readonly renderItem: (item: T) => ReactNode;
  readonly emptyMessage?: string;
  readonly styled?: boolean;
}

export function DataBoundList<T>({ bindingKey, loadBinding, selectItems, itemKey, renderItem, emptyMessage = "No visible records.", styled = false }: DataBoundListProps<T>) {
  const [items, setItems] = useState<readonly T[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  useEffect(() => {
    const controller = new AbortController();
    setLoading(true); setError(null);
    void loadBinding(bindingKey, controller.signal)
      .then((result) => setItems(selectItems(result.data)))
      .catch((failure: unknown) => { if (!controller.signal.aborted) setError(failure instanceof Error ? failure.message : "Data source unavailable."); })
      .finally(() => { if (!controller.signal.aborted) setLoading(false); });
    return () => controller.abort();
  }, [bindingKey, loadBinding, selectItems]);
  return <section aria-busy={loading} className={styled ? "bwhq-data-list" : undefined}>
    {loading && <p role="status">Loading…</p>}
    {error && <p role="alert">{error}</p>}
    {!loading && !error && items.length === 0 && <p>{emptyMessage}</p>}
    {!loading && !error && items.length > 0 && <ul>{items.map((item) => <li key={itemKey(item)}>{renderItem(item)}</li>)}</ul>}
  </section>;
}
```

## First-class module recipes

Use an unstyled native block when the module alone is sufficient. Use its styled composition to place a supported `core.text` heading and the module inside a supported stack container. Both invoke the same native renderer and secured API.

[Account Admin](#component-account-admin) [Goclaw](#component-goclaw) [Universal Inbox](#component-universal-inbox) [Support Lanes](#component-support-lanes) [Active Workplace](#component-active-workplace) [Ai Insights](#component-ai-insights) [Calendar](#component-calendar) [Chat Rooms](#component-chat-rooms) [Checklists Signoffs](#component-checklists-signoffs) [Company Iq](#component-company-iq) [Company News](#component-company-news) [Contacts](#component-contacts) [Conversations](#component-conversations) [Discussion Boards](#component-discussion-boards) [Dynamic Records](#component-module-dynamic-records) [Favorites](#component-favorites) [Files](#component-files) [Global Search](#component-global-search) [Knowledge Articles](#component-knowledge-articles) [Knowledge Core](#component-knowledge-core) [Knowledge Finder](#component-knowledge-finder) [Mail Reader](#component-mail-reader) [Notifications](#component-notifications) [Ops Atlas](#component-ops-atlas) [Payments Module](#component-payments-module) [Record Activity](#component-record-activity) [Record Graph](#component-record-graph) [Connected Work](#component-connected-work) [Reservations](#component-reservations) [Web Links](#component-web-links) [Work Orders](#component-work-orders) [Record Types](#component-record-types)

## Every module and operation

Expand a surface to copy both page-block forms and inspect every browser → HTTP → service → SQL chain. “Server API only” means the endpoint is implemented but the bundled component does not currently call it. “Not observed” means no runtime observation file was supplied; it is not a failure claim.

****Account Admin** `module.account-admin` 0 operations**

**API base:** `/api/account-admin`
**Renderer:** `AccountAdminModule`
**SDK descriptor:** `packages/module-sdk/src/administrationPages.ts:4`

#### Unstyled native block

```
{
  "_id": "account-admin-module",
  "_type": "module.account-admin",
  "props": {
    "title": "Account Admin"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "account-admin-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "account-admin-heading",
      "_type": "core.text",
      "_parent": "account-admin-section",
      "props": {
        "text": "Account Admin",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "account-admin-module",
      "_type": "module.account-admin",
      "props": {
        "title": "Account Admin"
      },
      "children": [],
      "_parent": "account-admin-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |

****Goclaw** `module.goclaw` 7 operations**

**API base:** `/api/goclaw/approvals`
**Renderer:** `GoClawModule`
**SDK descriptor:** `packages/module-sdk/src/goclaw.ts:1`

#### Unstyled native block

```
{
  "_id": "goclaw-module",
  "_type": "module.goclaw",
  "props": {
    "title": "Goclaw"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "goclaw-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "goclaw-heading",
      "_type": "core.text",
      "_parent": "goclaw-section",
      "props": {
        "text": "Goclaw",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "goclaw-module",
      "_type": "module.goclaw",
      "props": {
        "title": "Goclaw"
      },
      "children": [],
      "_parent": "goclaw-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/goclaw/approvals` | Server API only | `IActionApprovalService.GetApprovalQueueAsync` | `sp_AiAction_GetApprovalQueueSecured` | declared-interface
not-observed |
| **GET**
`/api/goclaw/approvals/lego/catalog` | Server API only | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **GET**
`/api/goclaw/approvals/lego/presentation` | Server API only | `IActionApprovalService.GetApprovalQueueAsync` | `sp_AiAction_GetApprovalQueueSecured` | declared-interface
not-observed |
| **POST**
`/api/goclaw/approvals/{suggestionBatchId:guid}/approve` | Server API only | `IActionApprovalService.ApproveSuggestionBatchAsync` | `sp_AiAction_EditAndApproveSuggestionBatch` | declared-interface
not-observed |
| **POST**
`/api/goclaw/approvals/{suggestionBatchId:guid}/reject` | Server API only | `IActionApprovalService.RejectSuggestionBatchAsync` | `sp_AiAction_RejectSuggestionBatch` | declared-interface
not-observed |
| **POST**
`/api/goclaw/approvals/{suggestionBatchId:guid}/take-over` | Server API only | `IActionApprovalService.TakeOverSuggestionBatchAsync` | `sp_AiAction_ReviewDisposition` | declared-interface
not-observed |
| **POST**
`/api/goclaw/approvals/{suggestionBatchId:guid}/retry` | Server API only | `IActionApprovalService.RetrySuggestionBatchAsync` | `sp_AiAction_ReviewDisposition` | declared-interface
not-observed |

****Universal Inbox** `core.universal-inbox` 21 operations**

**API base:** `/api/inbox`
**Renderer:** `UniversalInboxPageModule`
**SDK descriptor:** `packages/module-sdk/src/universalInboxPage.ts:1`

#### Unstyled native block

```
{
  "_id": "universal-inbox-module",
  "_type": "core.universal-inbox",
  "props": {
    "title": "Universal Inbox"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "universal-inbox-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "universal-inbox-heading",
      "_type": "core.text",
      "_parent": "universal-inbox-section",
      "props": {
        "text": "Universal Inbox",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "universal-inbox-module",
      "_type": "core.universal-inbox",
      "props": {
        "title": "Universal Inbox"
      },
      "children": [],
      "_parent": "universal-inbox-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/inbox/support-lanes` | Server API only | `ISupportLaneService.ListLanesAsync` | `sp_Inbox_ListSupportLanesSecured` | declared-interface
not-observed |
| **GET**
`/api/inbox/support-lanes/{laneId:guid}` | Server API only | `ISupportLaneService.GetLaneAsync` | `sp_Inbox_ListSupportLanesSecured` | declared-interface
not-observed |
| **GET**
`/api/inbox/support-lanes/options` | Server API only | `ISupportLaneService.ListLaneOptionsAsync` | `sp_Inbox_ListSupportLaneOptionsSecured` | declared-interface
not-observed |
| **POST**
`/api/inbox/support-lanes` | Server API only | `ISupportLaneService.SaveLaneAsync` | `sp_Inbox_SaveSupportLaneSecured` | declared-interface
not-observed |
| **PUT**
`/api/inbox/support-lanes/{laneId:guid}` | Server API only | `ISupportLaneService.SaveLaneAsync` | `sp_Inbox_SaveSupportLaneSecured` | declared-interface
not-observed |
| **POST**
`/api/inbox/support-lanes/{laneId:guid}/retire` | Server API only | `ISupportLaneService.RetireLaneAsync` | `sp_Inbox_RetireSupportLaneSecured` | declared-interface
not-observed |
| **GET**
`/api/inbox/lego-catalog` | `getInboxLegoCatalog` | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **GET**
`/api/inbox/lego-presentation` | `getInboxLegoPresentation` | `IUniversalInboxService.GetQueueAsync` | `sp_Inbox_GetQueueSecured` | declared-interface
not-observed |
| **GET**
`/api/inbox/items` | Server API only | `IUniversalInboxService.GetQueueAsync` | `sp_Inbox_GetQueueSecured` | declared-interface
not-observed |
| **GET**
`/api/inbox/email-channels/ticketing` | Server API only | `IUniversalInboxService.GetEmailTicketingSettingsAsync` | `sp_Inbox_GetEmailTicketingSettingsSecured` | declared-interface
not-observed |
| **PUT**
`/api/inbox/email-channels/{channelConnectionId:guid}/ticketing` | Server API only | `IUniversalInboxService.SetEmailTicketingAsync` | `sp_Inbox_SetEmailTicketingSecured` | declared-interface
not-observed |
| **GET**
`/api/inbox/items/{inboxItemId:guid}` | Server API only | `IUniversalInboxService.GetItemAsync` | `sp_Inbox_GetItemDetailSecured` | declared-interface
not-observed |
| **GET**
`/api/inbox/badge` | Server API only | `IUniversalInboxService.GetBadgeAsync` | `sp_GetInboxBadgeSecured` | declared-interface
not-observed |
| **GET**
`/api/inbox/notifications` | Server API only | `IUniversalInboxService.GetNotificationsAsync` | `sp_GetInboxNotificationsSecured` | declared-interface
not-observed |
| **GET**
`/api/inbox/delivery/debug` | Server API only | `IUniversalInboxService.GetDeliveryDebugAsync` | `sp_GetDeliveryDebugSecured` | declared-interface
not-observed |
| **POST**
`/api/inbox/delivery/{outboundMessageId:guid}/retry` | Server API only | `IUniversalInboxService.RetryDeliveryAsync` | `sp_RetryOutboundMessage` | declared-interface
not-observed |
| **PUT**
`/api/inbox/items/{inboxItemId:guid}/human-state` | Server API only | `ITenantInboxHumanStateAudit.ExecuteAsync` | `WriteAuditLog`
`sp_Inbox_MarkRead`
`sp_Inbox_SetStatusSecured` | delegated-interface
not-observed |
| **GET**
`/api/inbox/badge/indicator` | Server API only | `IUniversalInboxService.GetBadgeIndicatorAsync` | `sp_GetInboxBadgeIndicatorSecured` | declared-interface
not-observed |
| **GET**
`/api/inbox/channels/ticketing` | Server API only | `IUniversalInboxService.GetChannelTicketingSettingsAsync` | `sp_Inbox_GetChannelTicketingSettingsSecured` | declared-interface
not-observed |
| **PUT**
`/api/inbox/channels/{channelConnectionId:guid}/ticketing` | Server API only | `IUniversalInboxService.SetChannelTicketingAsync` | `sp_Inbox_SetChannelTicketingSecured` | declared-interface
not-observed |
| **POST**
`/api/inbox/items/{inboxItemId:guid}/reply` | Server API only | `IUniversalInboxService.ReplyAsync` | `sp_Inbox_ReplySecured` | declared-interface
not-observed |

****Support Lanes** `module.support-lanes` 0 operations**

**API base:** `/api/inbox/support-lanes`
**Renderer:** `SupportLaneWorkspaceModule`
**SDK descriptor:** `packages/module-sdk/src/universalInboxPage.ts:8`

#### Unstyled native block

```
{
  "_id": "support-lanes-module",
  "_type": "module.support-lanes",
  "props": {
    "title": "Support Lanes"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "support-lanes-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "support-lanes-heading",
      "_type": "core.text",
      "_parent": "support-lanes-section",
      "props": {
        "text": "Support Lanes",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "support-lanes-module",
      "_type": "module.support-lanes",
      "props": {
        "title": "Support Lanes"
      },
      "children": [],
      "_parent": "support-lanes-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |

****Active Workplace** `module.active-workplace` 14 operations**

**API base:** `/api/modules/active-workplace`
**Renderer:** `ActiveWorkplaceModule`
**SDK descriptor:** `packages/module-sdk/src/activeWorkplace.ts:3`

#### Unstyled native block

```
{
  "_id": "active-workplace-module",
  "_type": "module.active-workplace",
  "props": {
    "title": "Active Workplace"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "active-workplace-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "active-workplace-heading",
      "_type": "core.text",
      "_parent": "active-workplace-section",
      "props": {
        "text": "Active Workplace",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "active-workplace-module",
      "_type": "module.active-workplace",
      "props": {
        "title": "Active Workplace"
      },
      "children": [],
      "_parent": "active-workplace-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/active-workplace` | `listActiveWorkplaces` | `ITenantActiveWorkplaceService.ListAsync` | `sp_ActiveWorkplace_ListSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/active-workplace/lego/catalog` | Server API only | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **GET**
`/api/modules/active-workplace/lego/lookups/{lookupId:guid}` | Server API only | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **GET**
`/api/modules/active-workplace/lego/presentation` | Server API only | `ITenantActiveWorkplaceService.ListAsync` | `sp_ActiveWorkplace_ListSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/active-workplace` | `createActiveWorkplace` | `ITenantActiveWorkplaceService.CreateAsync` | `sp_ActiveWorkplace_CreateWithDynamicFieldsSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/active-workplace/{activeWorkplaceId:guid}` | `getActiveWorkplace` | `ITenantActiveWorkplaceService.GetAsync` | `sp_ActiveWorkplace_GetSecured`
`sp_Tenant_RecordDynamicFields_GetSecured` | delegated-interface
not-observed |
| **PATCH**
`/api/modules/active-workplace/{activeWorkplaceId:guid}` | `updateActiveWorkplace` | `ITenantActiveWorkplaceService.UpdateAsync` | `sp_ActiveWorkplace_UpdateWithDynamicFieldsSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/active-workplace/{activeWorkplaceId:guid}/status` | `setActiveWorkplaceStatus` | `ITenantActiveWorkplaceService.SetStatusAsync` | `sp_ActiveWorkplace_SetStatusSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/active-workplace/{activeWorkplaceId:guid}/participants/catalog` | `getActiveWorkplaceParticipantCatalog` | `ITenantActiveWorkplaceService.GetParticipantCatalogAsync` | `sp_ActiveWorkplace_GetParticipantCatalogSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/active-workplace/{activeWorkplaceId:guid}/participants` | `addActiveWorkplaceParticipant` | `ITenantActiveWorkplaceService.AddParticipantAsync` | `sp_ActiveWorkplace_AddParticipantSecured` | declared-interface
not-observed |
| **DELETE**
`/api/modules/active-workplace/{activeWorkplaceId:guid}/participants/{activeWorkplaceParticipantId:guid}` | `removeActiveWorkplaceParticipant` | `ITenantActiveWorkplaceService.RemoveParticipantAsync` | `sp_ActiveWorkplace_RemoveParticipantSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/active-workplace/{activeWorkplaceId:guid}/activity` | `recordActiveWorkplaceActivity` | `ITenantActiveWorkplaceService.RecordActivityAsync` | `sp_ActiveWorkplace_RecordActivitySecured` | declared-interface
not-observed |
| **POST**
`/api/modules/active-workplace/{activeWorkplaceId:guid}/graph/refresh` | `refreshActiveWorkplaceGraph` | `ITenantActiveWorkplaceService.RefreshGraphAsync` | `sp_ActiveWorkplace_RefreshGraphSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/active-workplace/{activeWorkplaceId:guid}/playback` | `getActiveWorkplacePlayback` | `ITenantActiveWorkplaceService.GetPlaybackAsync` | `sp_ActiveWorkplace_GetPlaybackSecured` | declared-interface
not-observed |

****Ai Insights** `module.ai-insights` 8 operations**

**API base:** `/api/modules/ai-insights`
**Renderer:** `AiInsightsModule`
**SDK descriptor:** `packages/module-sdk/src/aiInsights.ts:1`

#### Unstyled native block

```
{
  "_id": "ai-insights-module",
  "_type": "module.ai-insights",
  "props": {
    "title": "Ai Insights"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "ai-insights-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "ai-insights-heading",
      "_type": "core.text",
      "_parent": "ai-insights-section",
      "props": {
        "text": "Ai Insights",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "ai-insights-module",
      "_type": "module.ai-insights",
      "props": {
        "title": "Ai Insights"
      },
      "children": [],
      "_parent": "ai-insights-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/ai-insights` | `listAiInsights` | `ITenantAiInsightsService.ListAsync` | `sp_AiInsights_ListSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/ai-insights/{insightId:guid}` | `getAiInsight` | `ITenantAiInsightsService.GetAsync` | `sp_AiInsights_GetSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/ai-insights/{insightId:guid}/state` | `setAiInsightState` | `ITenantAiInsightsService.SetStateAsync` | `sp_AiInsights_SetStateSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/ai-insights/settings` | Server API only | `ITenantAiInsightsService.GetSettingsAsync` | `sp_AiInsights_GetProducerSettingsSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/ai-insights/settings` | Server API only | `ITenantAiInsightsService.SaveSettingsAsync` | `sp_AiInsights_SaveProducerSettingsSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/ai-insights/settings/directives` | Server API only | `ITenantAiInsightsService.SaveDirectiveAsync` | `sp_AiInsights_SaveDirectiveSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/ai-insights/settings/directives/{directiveId:guid}` | Server API only | `ITenantAiInsightsService.SaveDirectiveAsync` | `sp_AiInsights_SaveDirectiveSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/ai-insights/settings/starters/{directiveId:guid}` | Server API only | `ITenantAiInsightsService.SetStarterDirectiveAsync` | `sp_AiInsights_SetStarterDirectiveSecured` | declared-interface
not-observed |

****Calendar** `module.calendar` 8 operations**

**API base:** `/api/modules/calendar`
**Renderer:** `CalendarModule`
**SDK descriptor:** `packages/module-sdk/src/calendar.ts:3`

#### Unstyled native block

```
{
  "_id": "calendar-module",
  "_type": "module.calendar",
  "props": {
    "title": "Calendar"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "calendar-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "calendar-heading",
      "_type": "core.text",
      "_parent": "calendar-section",
      "props": {
        "text": "Calendar",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "calendar-module",
      "_type": "module.calendar",
      "props": {
        "title": "Calendar"
      },
      "children": [],
      "_parent": "calendar-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/calendar` | `listCalendarEvents` | `ITenantCalendarService.ListAsync` | `sp_Calendar_ListSecured`
`sp_Calendar_CreateSecured`
`sp_Calendar_UpdateSecured`
`sp_Developer_DeleteRecord`
`sp_Calendar_SetFavoriteSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/calendar/{recordId:guid}` | `getCalendarEvent` | `ITenantCalendarService.GetAsync` | `sp_Calendar_GetSecured`
`sp_Calendar_CreateSecured`
`sp_Calendar_UpdateSecured`
`sp_Developer_DeleteRecord`
`sp_Calendar_SetFavoriteSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/calendar` | `createCalendarEvent` | `ITenantCalendarAudit.ExecuteAsync` | `WriteAuditLog`
`sp_Calendar_CreateSecured`
`sp_Calendar_UpdateSecured`
`sp_Developer_DeleteRecord`
`sp_Calendar_SetFavoriteSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/calendar/{recordId:guid}` | `updateCalendarEvent` | `ITenantCalendarAudit.ExecuteAsync` | `WriteAuditLog`
`sp_Calendar_CreateSecured`
`sp_Calendar_UpdateSecured`
`sp_Developer_DeleteRecord`
`sp_Calendar_SetFavoriteSecured`
`sp_RecordScope_GetCurrentSecured`
`sp_Calendar_GetSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/calendar/capabilities` | Server API only | `ITenantCalendarService.GetCapabilitiesAsync` | `sp_Calendar_CreateSecured`
`sp_Calendar_UpdateSecured`
`sp_Developer_DeleteRecord`
`sp_Calendar_SetFavoriteSecured`
`sp_Runtime_GetModuleCapabilitiesSecured` | declared-interface
not-observed |
| **DELETE**
`/api/modules/calendar/{recordId:guid}` | `removeCalendarEvent` | `ITenantCalendarService.RemoveAsync` | `sp_Calendar_CreateSecured`
`sp_Calendar_UpdateSecured`
`sp_Developer_DeleteRecord`
`sp_Calendar_SetFavoriteSecured`
`sp_RecordScope_GetCurrentSecured`
`sp_Calendar_GetSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/calendar/{recordId:guid}/favorite` | `setCalendarFavorite` | `ITenantCalendarService.SetFavoriteAsync` | `sp_Calendar_CreateSecured`
`sp_Calendar_UpdateSecured`
`sp_Developer_DeleteRecord`
`sp_Calendar_SetFavoriteSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/calendar/lego/catalog` | Server API only | `Unresolved` | Unresolved | computed-read-contract
not-observed |

****Chat Rooms** `module.chat-rooms` 14 operations**

**API base:** `/api/modules/chat-rooms`
**Renderer:** `ChatRoomsModule`
**SDK descriptor:** `packages/module-sdk/src/chatRooms.ts:3`

#### Unstyled native block

```
{
  "_id": "chat-rooms-module",
  "_type": "module.chat-rooms",
  "props": {
    "title": "Chat Rooms"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "chat-rooms-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "chat-rooms-heading",
      "_type": "core.text",
      "_parent": "chat-rooms-section",
      "props": {
        "text": "Chat Rooms",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "chat-rooms-module",
      "_type": "module.chat-rooms",
      "props": {
        "title": "Chat Rooms"
      },
      "children": [],
      "_parent": "chat-rooms-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/chat-rooms` | `listChatRooms` | `ITenantChatRoomsService.ListAsync` | `sp_ChatRooms_ListSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/chat-rooms/{recordId:guid}` | Server API only | `ITenantChatRoomsService.GetAsync` | `sp_ChatRooms_GetSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/chat-rooms` | `createChatRoom` | `ITenantChatRoomAudit.ExecuteAsync` | `WriteAuditLog`
`sp_ChatRooms_CreateSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/chat-rooms/{recordId:guid}` | `updateChatRoom` | `ITenantChatRoomAudit.ExecuteAsync` | `WriteAuditLog`
`sp_ChatRooms_UpdateSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/chat-rooms/lego/catalog` | Server API only | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **DELETE**
`/api/modules/chat-rooms/{recordId:guid}` | `removeChatRoom` | `ITenantChatRoomsService.RemoveAsync` | `sp_ChatRooms_DeleteSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/chat-rooms/{recordId:guid}/messages` | `postChatMessage` | `ITenantChatRoomAudit.ExecuteAsync` | `WriteAuditLog`
`sp_ChatRooms_PostMessageSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/chat-rooms/{recordId:guid}/messages/{chatMessageId:guid}` | `updateChatMessage` | `ITenantChatRoomAudit.ExecuteAsync` | `WriteAuditLog`
`sp_ChatRooms_UpdateMessageSecured` | delegated-interface
not-observed |
| **DELETE**
`/api/modules/chat-rooms/{recordId:guid}/messages/{chatMessageId:guid}` | `removeChatMessage` | `ITenantChatRoomAudit.ExecuteAsync` | `WriteAuditLog`
`sp_ChatRooms_DeleteMessageSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/chat-rooms/{recordId:guid}/messages/{chatMessageId:guid}/reaction` | `setChatReaction` | `ITenantChatRoomsService.SetReactionAsync` | `sp_ChatRooms_SetReactionSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/chat-rooms/{recordId:guid}/members/{memberUserId:guid}` | `setChatRoomMember` | `ITenantChatRoomsService.SetMemberAsync` | `sp_ChatRooms_SetMemberSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/chat-rooms/{recordId:guid}/members/lookup` | `getChatRoomMemberLookup` | `ITenantChatRoomsService.GetMemberLookupAsync` | `sp_ChatRooms_GetMemberLookupSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/chat-rooms/{recordId:guid}/read` | `markChatRoomRead` | `ITenantChatRoomsService.MarkReadAsync` | `sp_ChatRooms_MarkReadSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/chat-rooms/{recordId:guid}/favorite` | `setChatRoomFavorite` | `ITenantChatRoomsService.SetFavoriteAsync` | `sp_ChatRooms_SetFavoriteSecured` | declared-interface
not-observed |

****Checklists Signoffs** `module.checklists-signoffs` 17 operations**

**API base:** `/api/modules/checklists-signoffs`
**Renderer:** `ChecklistsSignoffsModule`
**SDK descriptor:** `packages/module-sdk/src/checklistsSignoffs.ts:1`

#### Unstyled native block

```
{
  "_id": "checklists-signoffs-module",
  "_type": "module.checklists-signoffs",
  "props": {
    "title": "Checklists Signoffs"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "checklists-signoffs-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "checklists-signoffs-heading",
      "_type": "core.text",
      "_parent": "checklists-signoffs-section",
      "props": {
        "text": "Checklists Signoffs",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "checklists-signoffs-module",
      "_type": "module.checklists-signoffs",
      "props": {
        "title": "Checklists Signoffs"
      },
      "children": [],
      "_parent": "checklists-signoffs-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/checklists-signoffs/lego/catalog` | Server API only | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **GET**
`/api/modules/checklists-signoffs/lookups/{lookupId:guid}` | Server API only | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **GET**
`/api/modules/checklists-signoffs/templates` | `listChecklistTemplates` | `ITenantChecklistsService.ListTemplatesAsync` | `sp_Checklists_ListTemplatesSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/checklists-signoffs/templates` | `createChecklistTemplate` | `ITenantChecklistsService.CreateTemplateAsync` | `sp_Checklists_CreateTemplateSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/checklists-signoffs/templates/{checklistTemplateId:guid}` | `getChecklistTemplate` | `ITenantChecklistsService.GetTemplateAsync` | `sp_Checklists_GetTemplateSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/checklists-signoffs/templates/{checklistTemplateId:guid}` | `updateChecklistTemplate` | `ITenantChecklistsService.UpdateTemplateAsync` | `sp_Checklists_UpdateTemplateSecured` | declared-interface
not-observed |
| **DELETE**
`/api/modules/checklists-signoffs/templates/{checklistTemplateId:guid}` | `removeChecklistTemplate` | `ITenantChecklistsService.RemoveTemplateAsync` | `sp_Checklists_DeactivateTemplateSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/checklists-signoffs/runs` | `listChecklistRuns` | `ITenantChecklistsService.ListRunsAsync` | `sp_Checklists_ListRunsSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/checklists-signoffs/runs/{checklistRunId:guid}` | `getChecklistRun` | `ITenantChecklistsService.GetRunAsync` | `sp_Checklists_GetRunSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/checklists-signoffs/runs` | `startChecklistRun` | `ITenantChecklistsService.StartRunAsync` | `sp_Checklists_StartRunSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/checklists-signoffs/items/{checklistRunItemId:guid}` | `updateChecklistItem` | `ITenantChecklistsService.UpdateItemAsync` | `sp_Checklists_UpdateItemSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/checklists-signoffs/items/{checklistRunItemId:guid}/proof` | `attachChecklistProof` | `ITenantChecklistsService.AttachProofAsync` | `sp_Checklists_AttachProofSecured` | declared-interface
not-observed |
| **DELETE**
`/api/modules/checklists-signoffs/proof/{checklistItemEvidenceId:guid}` | `removeChecklistProof` | `ITenantChecklistsService.RemoveProofAsync` | `sp_Checklists_RemoveProofSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/checklists-signoffs/runs/{checklistRunId:guid}/submit` | `submitChecklistForSignoff` | `ITenantChecklistsService.SubmitAsync` | `sp_Checklists_SubmitForSignoffSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/checklists-signoffs/runs/{checklistRunId:guid}/cancel` | `cancelChecklistRun` | `ITenantChecklistRunCancellation.CancelRunAsync` | `sp_Checklists_CancelRunSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/checklists-signoffs/export/capability` | `getChecklistExportCapability` | `ITenantChecklistsExport.GetExportCapabilityAsync` | `sp_Checklists_GetExportCapabilitySecured` | declared-interface
not-observed |
| **GET**
`/api/modules/checklists-signoffs/export` | Server API only | `ITenantChecklistsExport.ExportAsync` | `sp_Checklists_ExportRunsSecured` | declared-interface
not-observed |

****Company Iq** `module.company-iq` 0 operations**

**API base:** `/api/modules/company-iq`
**Renderer:** `CompanyIqModule`
**SDK descriptor:** `packages/module-sdk/src/companyIq.ts:1`

#### Unstyled native block

```
{
  "_id": "company-iq-module",
  "_type": "module.company-iq",
  "props": {
    "title": "Company Iq"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "company-iq-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "company-iq-heading",
      "_type": "core.text",
      "_parent": "company-iq-section",
      "props": {
        "text": "Company Iq",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "company-iq-module",
      "_type": "module.company-iq",
      "props": {
        "title": "Company Iq"
      },
      "children": [],
      "_parent": "company-iq-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |

****Company News** `module.company-news` 9 operations**

**API base:** `/api/modules/company-news`
**Renderer:** `CompanyNewsModule`
**SDK descriptor:** `packages/module-sdk/src/companyNews.ts:3`

#### Unstyled native block

```
{
  "_id": "company-news-module",
  "_type": "module.company-news",
  "props": {
    "title": "Company News"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "company-news-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "company-news-heading",
      "_type": "core.text",
      "_parent": "company-news-section",
      "props": {
        "text": "Company News",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "company-news-module",
      "_type": "module.company-news",
      "props": {
        "title": "Company News"
      },
      "children": [],
      "_parent": "company-news-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/company-news/schema` | `getCompanyNewsLegoCatalog` | `ITenantCompanyNewsService.GetLegoCatalogAsync` | `sp_CompanyNews_GetLegoCatalogSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/company-news/lookups/{lookupId:guid}` | `getCompanyNewsLegoLookup` | `ITenantCompanyNewsService.GetLegoLookupAsync` | `sp_CompanyNews_GetLegoLookupSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/company-news` | `listCompanyNews` | `ITenantCompanyNewsService.ListAsync` | `sp_CompanyNews_ListSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/company-news/{recordId:guid}` | `getCompanyNews` | `ITenantCompanyNewsService.GetAsync` | `sp_CompanyNews_GetSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/company-news` | `createCompanyNews` | `ITenantCompanyNewsService.CreateAsync` | `sp_CompanyNews_CreateSecured`
`WriteAuditLog` | delegated-interface
not-observed |
| **PUT**
`/api/modules/company-news/{recordId:guid}` | `updateCompanyNews` | `ITenantCompanyNewsService.UpdateAsync` | `sp_CompanyNews_UpdateSecured`
`WriteAuditLog` | delegated-interface
not-observed |
| **PUT**
`/api/modules/company-news/{recordId:guid}/favorite` | `setCompanyNewsFavorite` | `ITenantCompanyNewsService.SetFavoriteAsync` | `sp_CompanyNews_SetFavoriteSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/company-news/{recordId:guid}/published` | `setCompanyNewsPublished` | `ITenantCompanyNewsService.SetPublishedAsync` | `sp_CompanyNews_SetPublishedSecured`
`WriteAuditLog` | delegated-interface
not-observed |
| **DELETE**
`/api/modules/company-news/{recordId:guid}` | `removeCompanyNews` | `ITenantCompanyNewsFencedRemoval.RemoveAsync` | `sp_CompanyNews_RemoveSecured` | delegated-interface
not-observed |

****Contacts** `module.contacts` 16 operations**

**API base:** `/api/modules/contacts`
**Renderer:** `ContactsModule`
**SDK descriptor:** `packages/module-sdk/src/contacts.ts:4`

#### Unstyled native block

```
{
  "_id": "contacts-module",
  "_type": "module.contacts",
  "props": {
    "title": "Contacts"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "contacts-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "contacts-heading",
      "_type": "core.text",
      "_parent": "contacts-section",
      "props": {
        "text": "Contacts",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "contacts-module",
      "_type": "module.contacts",
      "props": {
        "title": "Contacts"
      },
      "children": [],
      "_parent": "contacts-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/contacts/schema` | `getContactsLegoCatalog` | `ITenantContactsService.GetLegoCatalogAsync` | `sp_Contacts_GetLegoCatalogSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/contacts/lookups/{lookupId:guid}` | `getContactsLegoLookup` | `ITenantContactsService.GetLegoLookupAsync` | `sp_Contacts_GetLegoLookupSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/contacts/create-visibility-options` | `getContactCreateVisibilityOptions` | `ITenantContactsService.GetCreateVisibilityOptionsAsync` | `sp_Contacts_GetCreateVisibilityOptionsSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/contacts` | `listContacts` | `ITenantContactsService.ListAsync` | `sp_Contacts_ListSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/contacts/count` | `listContacts` | `ITenantContactsService.CountAsync` | `sp_Contacts_CountSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/contacts/list-preferences` | Server API only | `ITenantContactsListPreferences.GetListPreferencesAsync` | `sp_ContactsList_GetPreferencesSecured`
`sp_ContactsList_GetPublishedDefaults` | delegated-interface
not-observed |
| **PUT**
`/api/modules/contacts/list-preferences/{scope}` | Server API only | `ITenantContactsListPreferences.SaveListPreferencesAsync` | `sp_ContactsList_SavePreferencesSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/contacts/{recordId:guid}` | `getContact` | `ITenantContactsService.GetAsync` | `sp_Contacts_GetSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/contacts` | `createContact` | `ITenantContactsService.CreateAsync` | `sp_Contacts_CreateSecured`
`sp_Contacts_GetSecured`
`sp_Contacts_UpdateSecured`
`sp_RecordScope_GetCurrentSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/contacts/{recordId:guid}` | `updateContact` | `ITenantContactsService.UpdateAsync` | `sp_Contacts_GetSecured`
`sp_Contacts_UpdateSecured`
`sp_RecordScope_GetCurrentSecured`
`sp_Contacts_CreateSecured` | delegated-interface
not-observed |
| **DELETE**
`/api/modules/contacts/{recordId:guid}` | `removeContact` | `ITenantContactsFencedRemoval.RemoveAsync` | `sp_Contacts_GetSecured`
`sp_Developer_DeleteRecord`
`sp_RecordScope_GetCurrentSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/contacts/{recordId:guid}/favorite` | `setContactFavorite` | `ITenantContactsService.SetFavoriteAsync` | `sp_Contacts_SetFavoriteSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/contacts/{recordId:guid}/secure-fields/{fieldDefinitionId:guid}/reveal` | `revealContactSecureField` | `ITenantContactsSecureFields.RevealSecureFieldAsync` | `sp_Contacts_RevealSecureFieldSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/contacts/{recordId:guid}/secure-fields/{fieldDefinitionId:guid}` | `setContactSecureField` | `ITenantContactsSecureFields.SetSecureFieldAsync` | `sp_Contacts_GetSecured`
`sp_Contacts_SetSecureFieldSecured`
`sp_RecordScope_GetCurrentSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/contacts/export/capability` | `getContactExportCapability` | `ITenantContactsExport.GetExportCapabilityAsync` | `sp_Contacts_GetExportCapabilitySecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/contacts/export` | `exportContacts` | `ITenantContactsExport.ExportAsync` | `sp_Contacts_ExportSecured` | delegated-interface
not-observed |

****Conversations** `module.conversations` 13 operations**

**API base:** `/api/modules/conversations`
**Renderer:** `ConversationsModule`
**SDK descriptor:** `packages/module-sdk/src/conversations.ts:3`

#### Unstyled native block

```
{
  "_id": "conversations-module",
  "_type": "module.conversations",
  "props": {
    "title": "Conversations"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "conversations-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "conversations-heading",
      "_type": "core.text",
      "_parent": "conversations-section",
      "props": {
        "text": "Conversations",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "conversations-module",
      "_type": "module.conversations",
      "props": {
        "title": "Conversations"
      },
      "children": [],
      "_parent": "conversations-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/conversations` | `listConversations` | `ITenantConversationsService.ListAsync` | `sp_Conversations_ListSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/conversations/{recordId:guid}` | `getConversation` | `ITenantConversationsService.GetAsync` | `sp_Conversations_GetSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/conversations/{recordId:guid}/messages/{messageId:guid}/attachments/{fileId:guid}/content` | `downloadConversationAttachment` | `ITenantConversationsService.DownloadAttachmentAsync` | `sp_Conversations_GetAttachmentDownloadSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/conversations` | `createConversation` | `ITenantConversationAudit.ExecuteAsync` | `WriteAuditLog`
`sp_Conversations_CreateSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/conversations/{recordId:guid}` | `updateConversation` | `ITenantConversationAudit.ExecuteAsync` | `WriteAuditLog`
`sp_Conversations_UpdateSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/conversations/lego-catalog` | `getConversationsLegoCatalog` | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **GET**
`/api/modules/conversations/lego-presentation` | `getConversationsLegoPresentation` | `ITenantConversationsService.ListAsync` | `sp_Conversations_ListSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/conversations/capabilities` | Server API only | `ITenantConversationsService.GetCapabilitiesAsync` | `sp_Runtime_GetModuleCapabilitiesSecured` | declared-interface
not-observed |
| **DELETE**
`/api/modules/conversations/{recordId:guid}` | `removeConversation` | `ITenantConversationsService.RemoveAsync` | `sp_Conversations_DeleteSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/conversations/{recordId:guid}/messages` | `postConversationMessage` | `ITenantConversationAudit.ExecuteAsync` | `WriteAuditLog`
`sp_Conversations_ReplySecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/conversations/direct/scope` | Server API only | `ITenantConversationsService.GetDirectScopeAsync` | `sp_Conversations_GetDirectScopeSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/conversations/direct` | `sendDirectConversation` | `ITenantConversationsService.SendDirectAsync` | `sp_Conversations_SendDirectSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/conversations/{recordId:guid}/favorite` | `setConversationFavorite` | `ITenantConversationsService.SetFavoriteAsync` | `sp_Conversations_SetFavoriteSecured` | declared-interface
not-observed |

****Discussion Boards** `module.discussion-boards` 14 operations**

**API base:** `/api/modules/discussion-boards`
**Renderer:** `DiscussionBoardsModule`
**SDK descriptor:** `packages/module-sdk/src/discussionBoards.ts:3`

#### Unstyled native block

```
{
  "_id": "discussion-boards-module",
  "_type": "module.discussion-boards",
  "props": {
    "title": "Discussion Boards"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "discussion-boards-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "discussion-boards-heading",
      "_type": "core.text",
      "_parent": "discussion-boards-section",
      "props": {
        "text": "Discussion Boards",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "discussion-boards-module",
      "_type": "module.discussion-boards",
      "props": {
        "title": "Discussion Boards"
      },
      "children": [],
      "_parent": "discussion-boards-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/discussion-boards` | `listDiscussionBoards` | `ITenantDiscussionBoardsService.ListAsync` | `sp_DiscussionBoards_ListSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/discussion-boards/{recordId:guid}` | `getDiscussionBoard` | `ITenantDiscussionBoardsService.GetBoardAsync` | `sp_DiscussionBoards_GetBoardSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/discussion-boards` | `createDiscussionBoard` | `ITenantDiscussionBoardsService.CreateBoardAsync` | `sp_DiscussionBoards_CreateBoardSecured`
`WriteAuditLog` | delegated-interface
not-observed |
| **PUT**
`/api/modules/discussion-boards/{recordId:guid}` | `updateDiscussionBoard` | `ITenantDiscussionBoardsService.UpdateBoardAsync` | `sp_DiscussionBoards_UpdateBoardSecured`
`WriteAuditLog` | delegated-interface
not-observed |
| **GET**
`/api/modules/discussion-boards/lego/catalog` | Server API only | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **DELETE**
`/api/modules/discussion-boards/{recordId:guid}` | `removeDiscussionBoard` | `ITenantDiscussionBoardsService.RemoveBoardAsync` | `sp_DiscussionBoards_DeleteBoardSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/discussion-boards/{boardRecordId:guid}/topics` | `createDiscussionTopic` | `ITenantDiscussionBoardsService.CreateTopicAsync` | `sp_DiscussionBoards_CreateTopicSecured`
`WriteAuditLog` | delegated-interface
not-observed |
| **GET**
`/api/modules/discussion-boards/topics/{recordId:guid}` | Server API only | `ITenantDiscussionBoardsService.GetTopicAsync` | `sp_DiscussionBoards_GetTopicSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/discussion-boards/topics/{recordId:guid}` | `updateDiscussionTopic` | `ITenantDiscussionBoardsService.UpdateTopicAsync` | `sp_DiscussionBoards_UpdateTopicSecured`
`WriteAuditLog` | delegated-interface
not-observed |
| **DELETE**
`/api/modules/discussion-boards/topics/{recordId:guid}` | `removeDiscussionTopic` | `ITenantDiscussionBoardsService.RemoveTopicAsync` | `sp_DiscussionBoards_DeleteTopicSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/discussion-boards/topics/{topicRecordId:guid}/posts` | `postDiscussionReply` | `ITenantDiscussionBoardsService.PostReplyAsync` | `sp_DiscussionBoards_PostReplySecured`
`WriteAuditLog` | delegated-interface
not-observed |
| **PUT**
`/api/modules/discussion-boards/posts/{recordId:guid}` | `updateDiscussionPost` | `ITenantDiscussionBoardsService.UpdatePostAsync` | `sp_DiscussionBoards_UpdatePostSecured`
`WriteAuditLog` | delegated-interface
not-observed |
| **DELETE**
`/api/modules/discussion-boards/posts/{recordId:guid}` | `removeDiscussionPost` | `ITenantDiscussionBoardsService.RemovePostAsync` | `sp_DiscussionBoards_DeletePostSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/discussion-boards/records/{recordId:guid}/favorite` | `setDiscussionFavorite` | `ITenantDiscussionBoardsService.SetFavoriteAsync` | `sp_DiscussionBoards_SetFavoriteSecured` | delegated-interface
not-observed |

****Dynamic Records** `module.dynamic-records` 13 operations**

**API base:** `/api/modules/dynamic`
**Renderer:** `DynamicModulesModule`
**SDK descriptor:** `packages/module-sdk/src/dynamicModules.ts:3`

#### Unstyled native block

```
{
  "_id": "module-dynamic-records-module",
  "_type": "module.dynamic-records",
  "props": {
    "title": "Dynamic Records"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "module-dynamic-records-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "module-dynamic-records-heading",
      "_type": "core.text",
      "_parent": "module-dynamic-records-section",
      "props": {
        "text": "Dynamic Records",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "module-dynamic-records-module",
      "_type": "module.dynamic-records",
      "props": {
        "title": "Dynamic Records"
      },
      "children": [],
      "_parent": "module-dynamic-records-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/dynamic` | `listDynamicModuleSchemas` | `ITenantDynamicModulesService.ListSchemasAsync` | `sp_DynamicModules_ListSchemasSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/dynamic/{moduleKey}/schema` | `getDynamicModuleSchema` | `ITenantDynamicModulesService.GetSchemaAsync` | `sp_DynamicModules_GetSchemaSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/dynamic/{moduleKey}/lookups/{lookupId:guid}` | Server API only | `ITenantOperationalLegoLookupService.GetDynamicAsync` | `sp_Checklists_ListRunsSecured` | computed-read-contract
not-observed |
| **GET**
`/api/modules/dynamic/{moduleKey}/lego/catalog` | Server API only | `ITenantDynamicModulesService.GetSchemaAsync` | `sp_DynamicModules_GetSchemaSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/dynamic/{moduleKey}` | `listDynamicModuleRecords` | `ITenantDynamicModulesService.ListAsync` | `sp_DynamicModules_ListSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/dynamic/{moduleKey}/{recordId:guid}` | `getDynamicModuleRecord` | `ITenantDynamicModulesService.GetAsync` | `sp_DynamicModules_GetSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/dynamic/{moduleKey}` | `createDynamicModuleRecord` | `ITenantDynamicModulesService.CreateAsync` | `sp_DynamicModules_CreateSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/dynamic/{moduleKey}/{recordId:guid}` | `updateDynamicModuleRecord` | `ITenantDynamicModulesService.UpdateAsync` | `sp_DynamicModules_UpdateSecured` | delegated-interface
not-observed |
| **DELETE**
`/api/modules/dynamic/{moduleKey}/{recordId:guid}` | `deleteDynamicModuleRecord` | `ITenantDynamicModulesService.DeleteAsync` | `sp_Developer_DeleteRecord` | delegated-interface
not-observed |
| **PUT**
`/api/modules/dynamic/{moduleKey}/{recordId:guid}/favorite` | `setDynamicModuleFavorite` | `ITenantDynamicModulesService.SetFavoriteAsync` | `sp_DynamicModules_SetFavoriteSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/dynamic/caseflow-cases/{recordId:guid}/transition` | `transitionCaseFlowCase` | `ITenantDynamicModulesService.TransitionCaseFlowAsync` | `sp_CaseFlow_TransitionSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/dynamic/{moduleKey}/export/capability` | `getDynamicRecordExportCapability` | `ITenantDynamicRecordsExport.GetExportCapabilityAsync` | `sp_DynamicModules_GetExportCapabilitySecured` | declared-interface
not-observed |
| **GET**
`/api/modules/dynamic/{moduleKey}/export` | Server API only | `ITenantDynamicRecordsExport.ExportAsync` | `sp_DynamicModules_ExportSecured` | declared-interface
not-observed |

****Favorites** `module.favorites` 7 operations**

**API base:** `/api/modules/favorites`
**Renderer:** `FavoritesModule`
**SDK descriptor:** `packages/module-sdk/src/favorites.ts:3`

#### Unstyled native block

```
{
  "_id": "favorites-module",
  "_type": "module.favorites",
  "props": {
    "title": "Favorites"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "favorites-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "favorites-heading",
      "_type": "core.text",
      "_parent": "favorites-section",
      "props": {
        "text": "Favorites",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "favorites-module",
      "_type": "module.favorites",
      "props": {
        "title": "Favorites"
      },
      "children": [],
      "_parent": "favorites-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/favorites/schema` | `getFavoritesLegoCatalog` | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **GET**
`/api/modules/favorites/presentation` | Server API only | `ITenantFavoritesService.GetLegoPresentationAsync` | `sp_Favorites_ListSecured` | computed-read-contract
not-observed |
| **GET**
`/api/modules/favorites` | `listFavorites` | `ITenantFavoritesService.ListAsync` | `sp_Favorites_ListSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/favorites/{recordId:guid}` | `getFavorite` | `ITenantFavoritesService.GetAsync` | `sp_Favorites_GetSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/favorites/{recordId:guid}/state` | `getFavoriteState` | `ITenantFavoritesService.GetStateAsync` | `sp_Favorites_GetStateSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/favorites/{recordId:guid}/favorite` | `setFavorite` | `ITenantFavoritesService.SetAsync` | `sp_Favorites_SetSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/favorites/{recordId:guid}/preferences` | `updateFavoritePreferences` | `ITenantFavoritesService.UpdateAsync` | `sp_Favorites_UpdateSecured` | declared-interface
not-observed |

****Files** `module.files` 20 operations**

**API base:** `/api/modules/files`
**Renderer:** `FilesModule`
**SDK descriptor:** `packages/module-sdk/src/files.ts:3`

#### Unstyled native block

```
{
  "_id": "files-module",
  "_type": "module.files",
  "props": {
    "title": "Files"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "files-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "files-heading",
      "_type": "core.text",
      "_parent": "files-section",
      "props": {
        "text": "Files",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "files-module",
      "_type": "module.files",
      "props": {
        "title": "Files"
      },
      "children": [],
      "_parent": "files-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/files` | `listFiles` | `ITenantFilesService.ListAsync` | `sp_Files_ListSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/files/capabilities` | Server API only | `ITenantFilesService.GetCapabilitiesAsync` | `sp_Runtime_GetModuleCapabilitiesSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/files/personal-limit` | Server API only | `ITenantFilesService.GetPersonalLimitAsync` | `sp_FileStorage_GetPersonalFileLimitSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/files/personal-limit` | Server API only | `ITenantFilesService.SavePersonalLimitAsync` | `sp_FileStorage_SaveOrganizationPersonalFileLimitSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/files/{recordId:guid}` | `getFile` | `ITenantFilesService.GetAsync` | `sp_Files_GetSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/files/upload` | `uploadFile` | `ITenantFilesService.UploadAsync` | `sp_FileStorage_ReserveFilesUploadSecured`
`sp_FileStorage_CommitFilesUploadSecured`
`sp_FileStorage_RetireFilesUploadSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/files/{recordId:guid}` | `updateFile` | `ITenantFilesService.UpdateAsync` | `sp_Files_UpdateSecured`
`WriteAuditLog` | delegated-interface
not-observed |
| **DELETE**
`/api/modules/files/{recordId:guid}` | `removeFile` | `ITenantFilesService.RemoveAsync` | `sp_Files_RemoveSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/files/{recordId:guid}/attachments` | `attachFile` | `ITenantFilesService.AttachAsync` | `sp_Files_AttachSecured` | delegated-interface
not-observed |
| **DELETE**
`/api/modules/files/{recordId:guid}/attachments/{attachmentId:guid}` | `detachFile` | `ITenantFilesService.DetachAsync` | `sp_Files_DetachSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/files/{recordId:guid}/favorite` | `setFileFavorite` | `ITenantFilesService.SetFavoriteAsync` | `sp_Files_SetFavoriteSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/files/{recordId:guid}/comments` | `listFileComments` | `ITenantFilesService.ListCommentsAsync` | `sp_Documents_ListCommentsSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/files/{recordId:guid}/comments` | `addFileComment` | `ITenantFilesService.AddCommentAsync` | `sp_Documents_AddCommentSecured` | delegated-interface
not-observed |
| **DELETE**
`/api/modules/files/{recordId:guid}/comments/{commentId:guid}` | `removeFileComment` | `ITenantFilesService.RemoveCommentAsync` | `sp_Documents_RemoveCommentSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/files/lego/catalog` | Server API only | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **GET**
`/api/modules/files/{recordId:guid}/content` | `downloadFileContent` | `ITenantFilesService.DownloadAsync` | `sp_Files_GetDownloadSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/files/{recordId:guid}/versions` | `uploadFileVersion` | `ITenantFilesService.UploadVersionAsync` | `sp_FileStorage_RetireFilesUploadSecured`
`sp_FileStorage_ReserveFileVersionUploadSecured`
`sp_FileStorage_CommitFileVersionUploadSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/files/{recordId:guid}/versions` | `listFileVersions` | `ITenantFilesService.ListVersionsAsync` | `sp_Files_ListVersionsSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/files/{recordId:guid}/versions/{version:int}/content` | `downloadFileVersionContent` | `ITenantFilesService.DownloadVersionAsync` | `sp_Files_GetVersionDownloadSecured` | delegated-interface
not-observed |
| **GET**
`/api/tenant/native-message-attachments/{recordId:guid}/content` | `downloadNativeMessageAttachment` | `ITenantFilesService.DownloadNativeAttachmentAsync` | `sp_NativeMessageAttachments_GetDownloadSecured` | delegated-interface
not-observed |

****Global Search** `module.global-search` 3 operations**

**API base:** `/api/modules/global-search`
**Renderer:** `GlobalSearchModule`
**SDK descriptor:** `packages/module-sdk/src/globalSearch.ts:1`

#### Unstyled native block

```
{
  "_id": "global-search-module",
  "_type": "module.global-search",
  "props": {
    "title": "Global Search"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "global-search-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "global-search-heading",
      "_type": "core.text",
      "_parent": "global-search-section",
      "props": {
        "text": "Global Search",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "global-search-module",
      "_type": "module.global-search",
      "props": {
        "title": "Global Search"
      },
      "children": [],
      "_parent": "global-search-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/global-search` | `searchGlobalRecords` | `ITenantGlobalSearchService.SearchAsync` | `sp_GlobalSearch_SearchSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/global-search/count` | `searchGlobalRecords` | `ITenantGlobalSearchService.CountAsync` | `sp_GlobalSearch_CountSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/global-search/records/{recordId:guid}/favorite` | `setGlobalSearchFavorite` | `ITenantGlobalSearchService.SetFavoriteAsync` | `sp_Favorites_SetSecured` | declared-interface
not-observed |

****Knowledge Articles** `module.knowledge-articles` 7 operations**

**API base:** `/api/modules/knowledge-articles`
**Renderer:** `KnowledgeArticlesModule`
**SDK descriptor:** `packages/module-sdk/src/knowledgeArticles.ts:3`

#### Unstyled native block

```
{
  "_id": "knowledge-articles-module",
  "_type": "module.knowledge-articles",
  "props": {
    "title": "Knowledge Articles"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "knowledge-articles-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "knowledge-articles-heading",
      "_type": "core.text",
      "_parent": "knowledge-articles-section",
      "props": {
        "text": "Knowledge Articles",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "knowledge-articles-module",
      "_type": "module.knowledge-articles",
      "props": {
        "title": "Knowledge Articles"
      },
      "children": [],
      "_parent": "knowledge-articles-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/knowledge-articles` | `listKnowledgeArticles` | `ITenantKnowledgeArticlesService.ListAsync` | `sp_KnowledgeArticles_ListSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-articles/{recordId:guid}` | `getKnowledgeArticle` | `ITenantKnowledgeArticlesService.GetAsync` | `sp_KnowledgeArticles_GetSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-articles` | `createKnowledgeArticle` | `ITenantKnowledgeArticlesService.CreateAsync` | `sp_KnowledgeArticles_CreateSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/knowledge-articles/{recordId:guid}` | `updateKnowledgeArticle` | `ITenantKnowledgeArticlesService.UpdateAsync` | `sp_KnowledgeArticles_UpdateSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/knowledge-articles/{recordId:guid}/favorite` | `setKnowledgeArticleFavorite` | `ITenantKnowledgeArticlesService.SetFavoriteAsync` | `sp_KnowledgeArticles_SetFavoriteSecured` | delegated-interface
not-observed |
| **DELETE**
`/api/modules/knowledge-articles/{recordId:guid}` | Server API only | `ITenantKnowledgeArticlesService.RemoveAsync` | `sp_KnowledgeArticles_RemoveSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-articles/lego/catalog` | Server API only | `Unresolved` | Unresolved | computed-read-contract
not-observed |

****Knowledge Core** `module.knowledge-articles` 36 operations**

**API base:** `/api/modules/knowledge-core`
**Renderer:** `KnowledgeArticlesModule`
**SDK descriptor:** `packages/module-sdk/src/knowledgeCore.ts:1`

#### Unstyled native block

```
{
  "_id": "knowledge-core-module",
  "_type": "module.knowledge-articles",
  "props": {
    "title": "Knowledge Core"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "knowledge-core-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "knowledge-core-heading",
      "_type": "core.text",
      "_parent": "knowledge-core-section",
      "props": {
        "text": "Knowledge Core",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "knowledge-core-module",
      "_type": "module.knowledge-articles",
      "props": {
        "title": "Knowledge Core"
      },
      "children": [],
      "_parent": "knowledge-core-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/knowledge-core` | `listKnowledgeCore` | `IKnowledgeCoreService.ListAsync` | `sp_kc_ListKnowledgeItemsSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-core/{recordId:guid}` | `getKnowledgeCore` | `IKnowledgeCoreService.GetAsync` | `sp_kc_GetKnowledgeItemSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core` | `createKnowledgeCore` | `IKnowledgeCoreService.CreateDraftAsync` | `sp_kc_CreateKnowledgeItem` | delegated-interface
not-observed |
| **PUT**
`/api/modules/knowledge-core/{recordId:guid}` | `updateKnowledgeCore` | `IKnowledgeCoreService.UpdateDraftAsync` | `sp_kc_UpdateKnowledgeItem` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/{recordId:guid}/publish` | `publishKnowledgeCore` | `IKnowledgeCoreService.PublishAsync` | `sp_kc_PublishKnowledgeItem` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/{recordId:guid}/archive` | `archiveKnowledgeCore` | `IKnowledgeCoreService.ArchiveAsync` | `sp_kc_ArchiveKnowledgeItem` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-core/{recordId:guid}/revisions` | `getKnowledgeCoreRevisions` | `IKnowledgeCoreService.GetRevisionHistoryAsync` | `sp_kc_GetRevisionHistorySecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/{recordId:guid}/restore` | `restoreKnowledgeCoreRevision` | `IKnowledgeCoreService.RestoreRevisionAsDraftAsync` | `sp_kc_RestoreRevisionAsDraft` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-core/collections` | `listKnowledgeCoreCollections` | `IKnowledgeCoreService.ListCollectionsAsync` | `sp_kc_ListCollectionsSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/collections` | `createKnowledgeCoreCollection` | `IKnowledgeCoreService.CreateCollectionAsync` | `sp_kc_CreateCollection` | delegated-interface
not-observed |
| **PUT**
`/api/modules/knowledge-core/collections/{collectionId:guid}` | `updateKnowledgeCoreCollection` | `IKnowledgeCoreService.UpdateCollectionAsync` | `sp_kc_UpdateCollection` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/collections/{collectionId:guid}/items/{recordId:guid}` | `addKnowledgeCoreCollectionItem` | `IKnowledgeCoreService.AddToCollectionAsync` | `sp_kc_AddKnowledgeItemToCollection` | delegated-interface
not-observed |
| **DELETE**
`/api/modules/knowledge-core/collections/{collectionId:guid}/items/{recordId:guid}` | `removeKnowledgeCoreCollectionItem` | `IKnowledgeCoreService.RemoveFromCollectionAsync` | `sp_kc_RemoveKnowledgeItemFromCollection` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-core/{recordId:guid}/owners` | `getKnowledgeCoreOwners` | `IKnowledgeCoreService.GetOwnersAsync` | `sp_kc_GetKnowledgeOwnersSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/{recordId:guid}/owners` | `setKnowledgeCoreOwner` | `IKnowledgeCoreService.SetOwnerAsync` | `sp_kc_SetKnowledgeOwner` | delegated-interface
not-observed |
| **DELETE**
`/api/modules/knowledge-core/owners/{knowledgeOwnerId:guid}` | `removeKnowledgeCoreOwner` | `IKnowledgeCoreService.RemoveOwnerAsync` | `sp_kc_RemoveKnowledgeOwner` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-core/unowned` | `listUnownedKnowledgeCore` | `IKnowledgeCoreService.GetUnownedAsync` | `sp_kc_GetUnownedKnowledgeSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-core/assignment-lookup` | `getKnowledgeAssignmentLookup` | `IKnowledgeCoreService.GetAssignmentLookupAsync` | `sp_kc_GetAssignmentLookupSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-core/reviews` | `listKnowledgeReviews` | `IKnowledgeCoreService.ListDueReviewsAsync` | `sp_kc_ListDueReviewsSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/begin` | `beginKnowledgeReview` | `IKnowledgeCoreService.BeginReviewAsync` | `sp_kc_BeginReview` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/complete` | `completeKnowledgeReview` | `IKnowledgeCoreService.CompleteReviewAsync` | `sp_kc_CompleteReview` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/reassign` | `reassignKnowledgeReview` | `IKnowledgeCoreService.ReassignReviewAsync` | `sp_kc_ReassignReview` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-core/health` | `getKnowledgeHealth` | `IKnowledgeCoreService.GetHealthAsync` | `sp_kc_GetKnowledgeHealthSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-core/questions` | `listKnowledgeQuestions` | `IKnowledgeCoreService.ListQuestionsAsync` | `sp_kc_GetOpenQuestionsSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/questions` | `createKnowledgeQuestion` | `IKnowledgeCoreService.CreateQuestionAsync` | `sp_kc_CreateQuestion` | delegated-interface
not-observed |
| **PUT**
`/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}` | Server API only | `IKnowledgeQuestionLifecycleService.EditQuestionAsync` | `sp_kc_MutateQuestionSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/close` | Server API only | `IKnowledgeQuestionLifecycleService.CloseQuestionAsync` | `sp_kc_MutateQuestionSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/assign` | `assignKnowledgeQuestion` | `IKnowledgeCoreService.AssignQuestionAsync` | `sp_kc_AssignQuestion` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/answer` | `answerKnowledgeQuestion` | `IKnowledgeCoreService.AnswerQuestionAsync` | `sp_kc_AnswerQuestion` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/convert` | `convertKnowledgeQuestion` | `IKnowledgeCoreService.ConvertQuestionAsync` | `sp_kc_ConvertQuestionToKnowledge` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/{recordId:guid}/feedback` | `recordKnowledgeFeedback` | `IKnowledgeCoreService.RecordFeedbackAsync` | `sp_kc_RecordFeedback` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-core/{recordId:guid}/feedback` | `getKnowledgeFeedback` | `IKnowledgeCoreService.GetFeedbackSummaryAsync` | `sp_kc_GetKnowledgeFeedbackSummarySecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-core/{recordId:guid}/feedback/comments` | `listKnowledgeFeedbackComments` | `IKnowledgeCoreService.ListFeedbackCommentsAsync` | `sp_kc_ListFeedbackCommentsSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-core/gaps` | `getKnowledgeGaps` | `IKnowledgeCoreService.GetKnowledgeGapsAsync` | `sp_kc_GetKnowledgeGapsSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/knowledge-core/support-learning/candidates` | Server API only | `IKnowledgeCoreService.ListSupportLearningCandidatesAsync` | `sp_kc_GetSupportLearningCandidatesSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/knowledge-core/support-learning/candidates` | Server API only | `IKnowledgeCoreService.CreateSupportResolutionCandidateAsync` | `sp_kc_CreateSupportResolutionCandidate` | delegated-interface
not-observed |

****Knowledge Finder** `module.knowledge-finder` 0 operations**

**API base:** `/api/modules/knowledge-core`
**Renderer:** `KnowledgeFinderModule`
**SDK descriptor:** `packages/module-sdk/src/dailyWorkPages.ts:11`

#### Unstyled native block

```
{
  "_id": "knowledge-finder-module",
  "_type": "module.knowledge-finder",
  "props": {
    "title": "Knowledge Finder"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "knowledge-finder-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "knowledge-finder-heading",
      "_type": "core.text",
      "_parent": "knowledge-finder-section",
      "props": {
        "text": "Knowledge Finder",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "knowledge-finder-module",
      "_type": "module.knowledge-finder",
      "props": {
        "title": "Knowledge Finder"
      },
      "children": [],
      "_parent": "knowledge-finder-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |

****Mail Reader** `module.mail-reader` 10 operations**

**API base:** `/api/modules/mail-reader`
**Renderer:** `MailReaderModule`
**SDK descriptor:** `packages/module-sdk/src/mailReader.ts:3`

#### Unstyled native block

```
{
  "_id": "mail-reader-module",
  "_type": "module.mail-reader",
  "props": {
    "title": "Mail Reader"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "mail-reader-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "mail-reader-heading",
      "_type": "core.text",
      "_parent": "mail-reader-section",
      "props": {
        "text": "Mail Reader",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "mail-reader-module",
      "_type": "module.mail-reader",
      "props": {
        "title": "Mail Reader"
      },
      "children": [],
      "_parent": "mail-reader-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/mail-reader` | `listMailReaderMessages` | `ITenantMailReaderService.ListAsync` | `sp_MailReader_ListSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/mail-reader/{recordId:guid}` | `getMailReaderMessage` | `ITenantMailReaderService.GetAsync` | `sp_MailReader_GetSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/mail-reader/{recordId:guid}/read` | `setMailReaderRead` | `ITenantMailReaderService.SetReadAsync` | `sp_MailReader_SetReadSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/mail-reader/{recordId:guid}/archive` | `archiveMailReaderMessage` | `ITenantMailReaderService.ArchiveAsync` | `sp_MailReader_ArchiveSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/mail-reader/mailboxes` | `listMailReaderMailboxes` | `ITenantMailReaderService.ListMailboxesAsync` | `sp_MailReader_ListMailboxesSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/mail-reader/mailboxes` | `createMailReaderMailbox` | `ITenantMailReaderService.CreateMailboxAsync` | `sp_MailReader_CreateMailboxSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/mail-reader/mailboxes/{mailboxId:guid}` | `updateMailReaderMailbox` | `ITenantMailReaderService.UpdateMailboxAsync` | `sp_MailReader_UpdateMailboxSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/mail-reader/{recordId:guid}/favorite` | `setMailReaderFavorite` | `ITenantMailReaderService.SetFavoriteAsync` | `sp_MailReader_SetFavoriteSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/mail-reader/mailboxes/{mailboxRecordId:guid}/credentials/{purpose}` | `setMailReaderCredential` | `ITenantMailReaderService.SetMailboxCredentialAsync` | `sp_MailReader_SetMailboxCredentialSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/mail-reader/mailboxes/{mailboxRecordId:guid}/compose` | `composeMailReaderEmail` | `ITenantMailReaderService.ComposeAsync` | `sp_Conversations_CreateSecured`
`sp_Conversations_ReplySecured`
`sp_MailReader_ListMailboxesSecured` | delegated-interface
not-observed |

****Notifications** `module.notifications` 6 operations**

**API base:** `/api/modules/notifications`
**Renderer:** `NotificationsModule`
**SDK descriptor:** `packages/module-sdk/src/notifications.ts:1`

#### Unstyled native block

```
{
  "_id": "notifications-module",
  "_type": "module.notifications",
  "props": {
    "title": "Notifications"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "notifications-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "notifications-heading",
      "_type": "core.text",
      "_parent": "notifications-section",
      "props": {
        "text": "Notifications",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "notifications-module",
      "_type": "module.notifications",
      "props": {
        "title": "Notifications"
      },
      "children": [],
      "_parent": "notifications-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/notifications` | `listNotifications` | `ITenantNotificationsService.ListAsync` | `sp_Notifications_ListSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/notifications/lego-catalog` | `getNotificationsLegoCatalog` | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **GET**
`/api/modules/notifications/lego-presentation` | `getNotificationsLegoPresentation` | `ITenantNotificationsService.ListAsync` | `sp_Notifications_ListSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/notifications/{notificationId:guid}` | `getNotification` | `ITenantNotificationsService.GetAsync` | `sp_Notifications_GetSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/notifications/{notificationId:guid}/state` | `setNotificationState` | `ITenantNotificationsService.SetStateAsync` | `sp_Notifications_SetStateSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/notifications/{notificationId:guid}/source-favorite` | `setNotificationSourceFavorite` | `ITenantNotificationsService.SetSourceFavoriteAsync` | `sp_Notifications_SetSourceFavoriteSecured` | declared-interface
not-observed |

****Ops Atlas** `module.ops-atlas` 0 operations**

**API base:** `/api/modules/ops-atlas`
**Renderer:** `OpsAtlasModule`
**SDK descriptor:** `packages/module-sdk/src/opsAtlas.ts:1`

#### Unstyled native block

```
{
  "_id": "ops-atlas-module",
  "_type": "module.ops-atlas",
  "props": {
    "title": "Ops Atlas"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "ops-atlas-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "ops-atlas-heading",
      "_type": "core.text",
      "_parent": "ops-atlas-section",
      "props": {
        "text": "Ops Atlas",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "ops-atlas-module",
      "_type": "module.ops-atlas",
      "props": {
        "title": "Ops Atlas"
      },
      "children": [],
      "_parent": "ops-atlas-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |

****Payments Module** `API-only` 14 operations**

**API base:** `/api/modules/payments`
**Renderer:** `Not a page renderer`
**SDK descriptor:** `packages/module-sdk/src/payments.ts:1`

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/payments/settings` | `getTenantPaymentSettings` | `ITenantPaymentsService.GetSettingsAsync` | `sp_TenantPayments_GetSettingsSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/payments/settings/{moduleKey}` | `updateTenantPaymentPolicy` | `ITenantPaymentsService.UpdatePolicyAsync` | `sp_TenantPayments_UpdatePolicySecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/payments/connectors` | `upsertTenantPaymentConnector` | `ITenantPaymentsService.UpsertConnectorAsync` | `sp_TenantPayments_UpsertConnectorSecured` | declared-interface
not-observed |
| **DELETE**
`/api/modules/payments/connectors/{connectorId:guid}` | `deactivateTenantPaymentConnector` | `ITenantPaymentsService.DeactivateConnectorAsync` | `sp_TenantPayments_DeactivateConnectorSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/payments/methods` | Server API only | `ITenantPaymentsService.ListMethodsAsync` | `sp_TenantPayments_ListMethodsSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/payments/methods` | `registerTenantPaymentMethod` | `ITenantPaymentsService.CreateMethodAsync` | `sp_TenantPayments_CreateMethodSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/payments/methods/{paymentMethodId:guid}` | `getTenantPaymentMethod` | `ITenantPaymentsService.GetMethodAsync` | `sp_TenantPayments_GetMethodSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/payments/methods/{paymentMethodId:guid}/default` | `setDefaultTenantPaymentMethod` | `ITenantPaymentsService.SetMethodDefaultAsync` | `sp_TenantPayments_SetMethodDefaultSecured` | declared-interface
not-observed |
| **DELETE**
`/api/modules/payments/methods/{paymentMethodId:guid}` | `revokeTenantPaymentMethod` | `ITenantPaymentsService.RevokeMethodAsync` | `sp_TenantPayments_RevokeMethodSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/payments/records/{recordId:guid}` | `getTenantRecordPayments` | `ITenantPaymentsService.GetRecordSummaryAsync` | `sp_TenantPayments_GetRecordSummarySecured` | declared-interface
not-observed |
| **POST**
`/api/modules/payments/records/{recordId:guid}/charges` | `createTenantRecordCharge` | `ITenantPaymentsService.CreateChargeAsync` | `sp_TenantPayments_CreateChargeSecured` | declared-interface
not-observed |
| **DELETE**
`/api/modules/payments/records/{recordId:guid}/charges/{chargeIntentId:guid}` | `cancelTenantRecordCharge` | `ITenantPaymentsService.CancelChargeAsync` | `sp_TenantPayments_CancelChargeSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/payments/attention` | Server API only | `ITenantPaymentsService.ListAttentionAsync` | `sp_TenantPayments_ListAttentionSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/payments/records/{recordId:guid}/charges/{chargeIntentId:guid}/attention` | `resolveTenantPaymentAttention` | `ITenantPaymentsService.ResolveAttentionAsync` | `sp_TenantPayments_ResolveAttentionSecured` | declared-interface
not-observed |

****Record Activity** `module.record-activity` 3 operations**

**API base:** `/api/modules/record-activity`
**Renderer:** `RecordActivityModule`
**SDK descriptor:** `packages/module-sdk/src/recordActivity.ts:3`

#### Unstyled native block

```
{
  "_id": "record-activity-module",
  "_type": "module.record-activity",
  "props": {
    "title": "Record Activity"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "record-activity-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "record-activity-heading",
      "_type": "core.text",
      "_parent": "record-activity-section",
      "props": {
        "text": "Record Activity",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "record-activity-module",
      "_type": "module.record-activity",
      "props": {
        "title": "Record Activity"
      },
      "children": [],
      "_parent": "record-activity-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/record-activity/records` | `searchRecordActivity` | `ITenantRecordActivityService.SearchAsync` | `sp_RecordActivity_SearchSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/record-activity/{recordId:guid}` | `getRecordActivity` | `ITenantRecordActivityService.GetAsync` | `sp_RecordActivity_GetSecured`
`sp_Calendar_GetSecured`
`sp_Calendar_CreateSecured`
`sp_Calendar_UpdateSecured`
`sp_Developer_DeleteRecord`
`sp_Calendar_SetFavoriteSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/record-activity/{recordId:guid}/favorite` | `setRecordActivityFavorite` | `ITenantRecordActivityService.SetFavoriteAsync` | `sp_Favorites_SetSecured` | declared-interface
not-observed |

****Record Graph** `module.record-graph` 10 operations**

**API base:** `/api/modules/record-graph`
**Renderer:** `RecordGraphModule`
**SDK descriptor:** `packages/module-sdk/src/recordGraph.ts:3`

#### Unstyled native block

```
{
  "_id": "record-graph-module",
  "_type": "module.record-graph",
  "props": {
    "title": "Record Graph"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "record-graph-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "record-graph-heading",
      "_type": "core.text",
      "_parent": "record-graph-section",
      "props": {
        "text": "Record Graph",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "record-graph-module",
      "_type": "module.record-graph",
      "props": {
        "title": "Record Graph"
      },
      "children": [],
      "_parent": "record-graph-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/record-graph/records` | `searchRecordGraph` | `ITenantRecordGraphService.SearchAsync` | `sp_RecordGraph_SearchSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/record-graph/{recordId:guid}` | `getRecordGraph` | `ITenantRecordGraphService.GetAsync` | `sp_RecordGraph_GetSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/record-graph/{recordId:guid}/relations` | Server API only | `ITenantRecordGraphService.ListRelatedAsync` | `sp_RecordGraph_ListRelatedSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/record-graph/{recordId:guid}/relations` | `addRecordGraphRelation` | `ITenantRecordGraphService.AddRelationAsync` | `sp_RecordGraph_AddRelationSecured` | declared-interface
not-observed |
| **DELETE**
`/api/modules/record-graph/relations/{recordRelationId:guid}` | `removeRecordGraphRelation` | `ITenantRecordGraphService.RemoveRelationAsync` | `sp_RecordGraph_RemoveRelationSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/record-graph/{recordId:guid}/favorite` | `setRecordGraphFavorite` | `ITenantRecordGraphService.SetFavoriteAsync` | `sp_Favorites_SetSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/record-graph/{recordId:guid}/knowledge` | `getRelatedKnowledge` | `ITenantRecordGraphService.GetRelatedKnowledgeAsync` | `sp_kc_GetRelatedKnowledgeSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/record-graph/{recordId:guid}/knowledge/candidates` | `getContextualKnowledge` | `ITenantRecordGraphService.GetContextualKnowledgeAsync` | `sp_kc_GetContextualKnowledgeCandidatesSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/record-graph/{recordId:guid}/knowledge` | `linkKnowledgeToRecord` | `ITenantRecordGraphService.LinkKnowledgeAsync` | `sp_kc_LinkKnowledgeToRecord` | declared-interface
not-observed |
| **DELETE**
`/api/modules/record-graph/knowledge-relations/{recordRelationId:guid}` | `unlinkKnowledgeFromRecord` | `ITenantRecordGraphService.UnlinkKnowledgeAsync` | `sp_kc_UnlinkKnowledgeFromRecord` | declared-interface
not-observed |

****Connected Work** `module.connected-work` 0 operations**

**API base:** `/api/modules/record-graph`
**Renderer:** `ConnectedWorkModule`
**SDK descriptor:** `packages/module-sdk/src/dailyWorkPages.ts:3`

#### Unstyled native block

```
{
  "_id": "connected-work-module",
  "_type": "module.connected-work",
  "props": {
    "title": "Connected Work"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "connected-work-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "connected-work-heading",
      "_type": "core.text",
      "_parent": "connected-work-section",
      "props": {
        "text": "Connected Work",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "connected-work-module",
      "_type": "module.connected-work",
      "props": {
        "title": "Connected Work"
      },
      "children": [],
      "_parent": "connected-work-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |

****Reservations** `module.reservations` 14 operations**

**API base:** `/api/modules/reservations`
**Renderer:** `ReservationsModule`
**SDK descriptor:** `packages/module-sdk/src/reservations.ts:5`

#### Unstyled native block

```
{
  "_id": "reservations-module",
  "_type": "module.reservations",
  "props": {
    "title": "Reservations"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "reservations-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "reservations-heading",
      "_type": "core.text",
      "_parent": "reservations-section",
      "props": {
        "text": "Reservations",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "reservations-module",
      "_type": "module.reservations",
      "props": {
        "title": "Reservations"
      },
      "children": [],
      "_parent": "reservations-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/reservations/products` | `listReservationProducts` | `ITenantReservationsService.ListProductsAsync` | `sp_ReservationProducts_ListSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/reservations/products` | `saveReservationProduct` | `ITenantReservationsService.UpsertProductAsync` | `sp_ReservationProducts_UpsertSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/reservations` | `listReservations` | `ITenantReservationsService.ListAsync` | `sp_Reservations_ListSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/reservations/assignees` | `listReservationAssignees` | `ITenantReservationsService.GetAssigneesAsync` | `sp_Reservations_GetAssigneesSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/reservations/capabilities` | Server API only | `ITenantReservationsService.GetCapabilitiesAsync` | `sp_Runtime_GetModuleCapabilitiesSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/reservations/{recordId:guid}` | `getReservation` | `ITenantReservationsService.GetAsync` | `sp_Reservations_GetSecured` | declared-interface
not-observed |
| **POST**
`/api/modules/reservations/purchase` | `purchaseReservation` | `ITenantReservationsService.PurchaseAsync` | `sp_Reservations_PurchaseSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/reservations/{recordId:guid}/status` | `setReservationStatus` | `ITenantReservationsService.SetStatusAsync` | `sp_Reservations_SetStatusSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/reservations/{recordId:guid}/schedule` | `rescheduleReservation` | `ITenantReservationsService.RescheduleAsync` | `sp_Reservations_RescheduleSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/reservations/{recordId:guid}/custom-fields` | `updateReservationCustomFields` | `ITenantReservationsService.UpdateCustomFieldsAsync` | `sp_Reservations_UpdateCustomFieldsSecured` | declared-interface
not-observed |
| **PUT**
`/api/modules/reservations/{recordId:guid}/followups` | `updateReservationFollowup` | `ITenantReservationsService.UpdateFollowupAsync` | `sp_ReservationFollowups_UpdateSecured` | declared-interface
not-observed |
| **GET**
`/api/modules/reservations/lego/catalog` | Server API only | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **GET**
`/api/modules/reservations/export/capability` | `getReservationExportCapability` | `ITenantReservationsExport.GetExportCapabilityAsync` | `sp_Reservations_GetExportCapabilitySecured` | declared-interface
not-observed |
| **GET**
`/api/modules/reservations/export` | `exportReservations` | `ITenantReservationsExport.ExportAsync` | `sp_Reservations_ExportSecured` | declared-interface
not-observed |

****Web Links** `module.web-links` 8 operations**

**API base:** `/api/modules/web-links`
**Renderer:** `WebLinksModule`
**SDK descriptor:** `packages/module-sdk/src/webLinks.ts:3`

#### Unstyled native block

```
{
  "_id": "web-links-module",
  "_type": "module.web-links",
  "props": {
    "title": "Web Links"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "web-links-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "web-links-heading",
      "_type": "core.text",
      "_parent": "web-links-section",
      "props": {
        "text": "Web Links",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "web-links-module",
      "_type": "module.web-links",
      "props": {
        "title": "Web Links"
      },
      "children": [],
      "_parent": "web-links-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/web-links/lego/catalog` | Server API only | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **GET**
`/api/modules/web-links/lookups/{lookupId:guid}` | Server API only | `Unresolved` | Unresolved | computed-read-contract
not-observed |
| **GET**
`/api/modules/web-links` | `listWebLinks` | `ITenantWebLinksService.ListAsync` | `sp_WebLinks_ListSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/web-links/{recordId:guid}` | `getWebLink` | `ITenantWebLinksService.GetAsync` | `sp_WebLinks_GetSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/web-links` | `createWebLink` | `ITenantWebLinksService.CreateAsync` | `sp_WebLinks_CreateSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/web-links/{recordId:guid}` | `updateWebLink` | `ITenantWebLinksService.UpdateAsync` | `sp_WebLinks_UpdateSecured` | delegated-interface
not-observed |
| **DELETE**
`/api/modules/web-links/{recordId:guid}` | `removeWebLink` | `ITenantWebLinksService.RemoveAsync` | `sp_WebLinks_GetSecured`
`sp_Developer_DeleteRecord` | delegated-interface
not-observed |
| **PUT**
`/api/modules/web-links/{recordId:guid}/favorite` | `setWebLinkFavorite` | `ITenantWebLinksService.SetFavoriteAsync` | `sp_WebLinks_SetFavoriteSecured` | delegated-interface
not-observed |

****Work Orders** `module.work-orders` 12 operations**

**API base:** `/api/modules/work-orders`
**Renderer:** `WorkOrdersModule`
**SDK descriptor:** `packages/module-sdk/src/workOrders.ts:3`

#### Unstyled native block

```
{
  "_id": "work-orders-module",
  "_type": "module.work-orders",
  "props": {
    "title": "Work Orders"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "work-orders-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "work-orders-heading",
      "_type": "core.text",
      "_parent": "work-orders-section",
      "props": {
        "text": "Work Orders",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "work-orders-module",
      "_type": "module.work-orders",
      "props": {
        "title": "Work Orders"
      },
      "children": [],
      "_parent": "work-orders-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |
| **GET**
`/api/modules/work-orders/schema` | `getWorkOrderLegoCatalog` | `ITenantWorkOrdersService.GetLegoCatalogAsync` | `sp_WorkOrders_GetLegoCatalogSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/work-orders/lookups/{lookupId:guid}` | `getWorkOrderLegoLookup` | `ITenantWorkOrdersService.GetLegoLookupAsync` | `sp_WorkOrders_GetLegoLookupSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/work-orders/{recordId:guid}/status-transitions` | `getWorkOrderStatusTransitions` | `ITenantWorkOrdersService.GetStatusTransitionsAsync` | `sp_WorkOrders_GetStatusTransitionsSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/work-orders` | `listWorkOrders` | `ITenantWorkOrdersService.ListAsync` | `sp_WorkOrders_ListSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/work-orders/{recordId:guid}` | `getWorkOrder` | `ITenantWorkOrdersService.GetAsync` | `sp_WorkOrders_GetSecured`
`sp_Tenant_RecordDynamicFields_GetSecured` | delegated-interface
not-observed |
| **POST**
`/api/modules/work-orders` | `createWorkOrder` | `ITenantWorkOrdersService.CreateAsync` | `sp_WorkOrders_CreateWithDynamicFieldsSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/work-orders/{recordId:guid}` | `updateWorkOrder` | `ITenantWorkOrdersService.UpdateAsync` | `sp_WorkOrders_GetSecured`
`sp_WorkOrders_UpdateWithDynamicFieldsSecured`
`sp_RecordScope_GetCurrentSecured` | delegated-interface
not-observed |
| **DELETE**
`/api/modules/work-orders/{recordId:guid}` | `removeWorkOrder` | `ITenantWorkOrdersService.RemoveAsync` | `sp_WorkOrders_GetSecured`
`sp_WorkOrders_RemoveSecured`
`sp_RecordScope_GetCurrentSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/work-orders/{recordId:guid}/status` | `setWorkOrderStatus` | `ITenantWorkOrdersService.SetStatusAsync` | `sp_WorkOrders_GetSecured`
`sp_WorkOrders_SetStatusSecured`
`sp_RecordScope_GetCurrentSecured` | delegated-interface
not-observed |
| **PUT**
`/api/modules/work-orders/{recordId:guid}/assignment` | `assignWorkOrder` | `ITenantWorkOrdersService.AssignAsync` | `sp_WorkOrders_GetSecured`
`sp_WorkOrders_AssignSecured`
`sp_RecordScope_GetCurrentSecured` | delegated-interface
not-observed |
| **GET**
`/api/modules/work-orders/export/capability` | `getWorkOrderExportCapability` | `ITenantWorkOrdersExport.GetExportCapabilityAsync` | `sp_WorkOrders_GetExportCapabilitySecured` | declared-interface
not-observed |
| **GET**
`/api/modules/work-orders/export` | Server API only | `ITenantWorkOrdersExport.ExportAsync` | `sp_WorkOrders_ExportSecured` | declared-interface
not-observed |

****Record Types** `module.record-types` 0 operations**

**API base:** `/api/runtime/record-types`
**Renderer:** `RecordTypesModule`
**SDK descriptor:** `packages/module-sdk/src/administrationPages.ts:12`

#### Unstyled native block

```
{
  "_id": "record-types-module",
  "_type": "module.record-types",
  "props": {
    "title": "Record Types"
  },
  "children": []
}
```

#### Styled composition

```
{
  "_id": "record-types-section",
  "_type": "core.container",
  "props": {
    "layout": "stack"
  },
  "children": [
    {
      "_id": "record-types-heading",
      "_type": "core.text",
      "_parent": "record-types-section",
      "props": {
        "text": "Record Types",
        "variant": "heading",
        "align": "left"
      },
      "children": []
    },
    {
      "_id": "record-types-module",
      "_type": "module.record-types",
      "props": {
        "title": "Record Types"
      },
      "children": [],
      "_parent": "record-types-section"
    }
  ]
}
```

| HTTP route | Browser function | Service member | Reviewed procedure | Evidence |
| --- | --- | --- | --- | --- |

## Complete browser, client and non-page route inventory

The API inventory keeps exported helpers even when they delegate and have no direct `fetch` call. Compiler-extracted route expressions are shown as written and resolved only when static source declares the path. Universal Inbox and GoClaw client methods are listed separately because they are package factories rather than top-level functions in `apps/tenant-runtime/src/api.ts`.

****Tenant runtime browser API** 307 exported functions**

Source: `apps/tenant-runtime/src/api.ts`

| Function | Transport/delegation | Return | Source |
| --- | --- | --- | --- |
| `acquirePageEditLock` | **PUT** `/api/runtime/pages/{value}/edit-lock` | `Promise<PageEditLock>` | `apps/tenant-runtime/src/api.ts:5226` |
| `activateRequiredTenantMfa` | Delegates through `isTenantRefreshSuccess, tenantAuthenticationRequest` | `Promise<TenantLoginSuccess>` | `apps/tenant-runtime/src/api.ts:4915` |
| `addActiveWorkplaceParticipant` | **POST** `/api/modules/active-workplace/{activeWorkplaceId}/participants` | `Promise<ActiveWorkplaceMutation>` | `apps/tenant-runtime/src/api.ts:3775` |
| `addFileComment` | **POST** `/api/modules/files/{recordId}/comments` | `Promise<FileCommentReceipt>` | `apps/tenant-runtime/src/api.ts:2356` |
| `addKnowledgeCoreCollectionItem` | **POST** `/api/modules/knowledge-core/collections/{collectionId}/items/{recordId}?sortOrder={value}` | `Promise<KnowledgeCollectionMutation>` | `apps/tenant-runtime/src/api.ts:4480` |
| `addRecordGraphRelation` | **PUT** `/api/modules/record-graph/{recordId}/relations` | `Promise<RecordGraphMutation>` | `apps/tenant-runtime/src/api.ts:3538` |
| `adoptTenantPage` | **POST** `pageAdoptionBase(pageKey)` | `Promise<TenantPageAdoptionResult>` | `apps/tenant-runtime/src/api.ts:5268` |
| `answerKnowledgeQuestion` | **POST** `/api/modules/knowledge-core/questions/{knowledgeQuestionId}/answer` | `Promise<KnowledgeQuestionMutation>` | `apps/tenant-runtime/src/api.ts:4718` |
| `archiveKnowledgeCore` | **POST** `/api/modules/knowledge-core/{recordId}/archive` | `Promise<KnowledgeCoreMutation>` | `apps/tenant-runtime/src/api.ts:4398` |
| `archiveMailReaderMessage` | **POST** `/api/modules/mail-reader/{recordId}/archive` | `inferred` | `apps/tenant-runtime/src/api.ts:3391` |
| `assignKnowledgeQuestion` | **POST** `/api/modules/knowledge-core/questions/{knowledgeQuestionId}/assign` | `Promise<KnowledgeQuestionMutation>` | `apps/tenant-runtime/src/api.ts:4702` |
| `assignWorkOrder` | **PUT** `/api/modules/work-orders/{recordId}/assignment` | `Promise<WorkOrderMutation>` | `apps/tenant-runtime/src/api.ts:1602` |
| `attachChecklistProof` | **POST** `/api/modules/checklists-signoffs/items/{checklistRunItemId}/proof` | `Promise<ChecklistMutation>` | `apps/tenant-runtime/src/api.ts:1725` |
| `attachFile` | **POST** `/api/modules/files/{recordId}/attachments` | `Promise<FileMutation>` | `apps/tenant-runtime/src/api.ts:2288` |
| `beginKnowledgeReview` | **POST** `/api/modules/knowledge-core/reviews/{reviewCycleId}/begin` | `Promise<KnowledgeReviewMutation>` | `apps/tenant-runtime/src/api.ts:4590` |
| `cancelChecklistRun` | **POST** `/api/modules/checklists-signoffs/runs/{checklistRunId}/cancel` | `Promise<ChecklistCancellation>` | `apps/tenant-runtime/src/api.ts:1755` |
| `cancelTenantRecordCharge` | **DELETE** `/api/modules/payments/records/{recordId}/charges/{chargeIntentId}` | `Promise<TenantPaymentMutation>` | `apps/tenant-runtime/src/api.ts:2059` |
| `changeTenantPassword` | Delegates through `accountSecurityPost, canonicalReceiptObject, invalidAccountSecurityResponse` | `Promise<TenantPasswordChangeReceipt>` | `apps/tenant-runtime/src/api.ts:4991` |
| `clearTenantSession` | Delegates through `clearPageGenerationTiming, publishTenantSessionChanged` | `void` | `apps/tenant-runtime/src/api.ts:614` |
| `closeKnowledgeQuestion` | Delegates through `mutateKnowledgeQuestion` | `Promise<KnowledgeQuestionMutation>` | `apps/tenant-runtime/src/api.ts:4691` |
| `completeKnowledgeReview` | **POST** `/api/modules/knowledge-core/reviews/{reviewCycleId}/complete` | `Promise<KnowledgeReviewMutation>` | `apps/tenant-runtime/src/api.ts:4608` |
| `completeTenantEmailChange` | Delegates through `canonicalReceiptObject, invalidPublicAccountResponse, publicAccountPost` | `Promise<void>` | `apps/tenant-runtime/src/api.ts:4959` |
| `completeTenantPasswordReset` | Delegates through `invalidPublicAccountResponse, publicAccountPost` | `Promise<void>` | `apps/tenant-runtime/src/api.ts:4950` |
| `composeMailReaderEmail` | **POST** `/api/modules/mail-reader/mailboxes/{mailboxRecordId}/compose` | `inferred` | `apps/tenant-runtime/src/api.ts:3388` |
| `convertKnowledgeQuestion` | **POST** `/api/modules/knowledge-core/questions/{knowledgeQuestionId}/convert` | `Promise<KnowledgeQuestionMutation>` | `apps/tenant-runtime/src/api.ts:4753` |
| `createActiveWorkplace` | **POST** `/api/modules/active-workplace` | `Promise<ActiveWorkplaceMutation>` | `apps/tenant-runtime/src/api.ts:3728` |
| `createCalendarEvent` | **POST** `/api/modules/calendar` | `Promise<CalendarMutation>` | `apps/tenant-runtime/src/api.ts:2131` |
| `createChatRoom` | **POST** `/api/modules/chat-rooms` | `Promise<ChatRoomMutation>` | `apps/tenant-runtime/src/api.ts:2965` |
| `createChecklistTemplate` | **POST** `/api/modules/checklists-signoffs/templates` | `Promise<ChecklistMutation>` | `apps/tenant-runtime/src/api.ts:1632` |
| `createCompanyNews` | **POST** `/api/modules/company-news` | `Promise<CompanyNewsMutation>` | `apps/tenant-runtime/src/api.ts:2689` |
| `createContact` | **POST** `/api/modules/contacts` | `Promise<ContactMutation>` | `apps/tenant-runtime/src/api.ts:1287` |
| `createConversation` | **POST** `/api/modules/conversations` | `Promise<ConversationMutation>` | `apps/tenant-runtime/src/api.ts:2534` |
| `createDiscussionBoard` | **POST** `/api/modules/discussion-boards` | `Promise<DiscussionMutation>` | `apps/tenant-runtime/src/api.ts:3139` |
| `createDiscussionTopic` | **POST** `/api/modules/discussion-boards/{boardRecordId}/topics` | `Promise<DiscussionMutation>` | `apps/tenant-runtime/src/api.ts:3173` |
| `createDynamicModuleRecord` | **POST** `/api/modules/dynamic/{moduleKey}` | `Promise<DynamicModuleMutation>` | `apps/tenant-runtime/src/api.ts:4168` |
| `createKnowledgeArticle` | **POST** `/api/modules/knowledge-articles` | `Promise<KnowledgeArticleMutation>` | `apps/tenant-runtime/src/api.ts:4284` |
| `createKnowledgeCore` | **POST** `/api/modules/knowledge-core` | `Promise<KnowledgeCoreMutation>` | `apps/tenant-runtime/src/api.ts:4359` |
| `createKnowledgeCoreCollection` | **POST** `/api/modules/knowledge-core/collections` | `Promise<KnowledgeCollectionMutation>` | `apps/tenant-runtime/src/api.ts:4457` |
| `createKnowledgeQuestion` | **POST** `/api/modules/knowledge-core/questions` | `Promise<KnowledgeQuestionMutation>` | `apps/tenant-runtime/src/api.ts:4675` |
| `createMailReaderMailbox` | **POST** `/api/modules/mail-reader/mailboxes` | `inferred` | `apps/tenant-runtime/src/api.ts:3377` |
| `createRecordType` | **POST** `/api/runtime/record-types` | `Promise<RecordType>` | `apps/tenant-runtime/src/api.ts:1142` |
| `createTenantRecordCharge` | **POST** `/api/modules/payments/records/{recordId}/charges` | `Promise<TenantPaymentMutation>` | `apps/tenant-runtime/src/api.ts:2049` |
| `createWebLink` | **POST** `/api/modules/web-links` | `Promise<WebLinkMutation>` | `apps/tenant-runtime/src/api.ts:2882` |
| `createWorkOrder` | **POST** `/api/modules/work-orders` | `Promise<WorkOrderMutation>` | `apps/tenant-runtime/src/api.ts:1562` |
| `deactivateTenantInboundEndpoint` | Delegates through `mutateTenantInboundEndpoint` | `inferred` | `apps/tenant-runtime/src/api.ts:4646` |
| `deactivateTenantPaymentConnector` | **DELETE** `/api/modules/payments/connectors/{connectorId}` | `Promise<TenantPaymentMutation>` | `apps/tenant-runtime/src/api.ts:1977` |
| `deleteDynamicModuleRecord` | **DELETE** `/api/modules/dynamic/{moduleKey}/{recordId}?expectedUpdatedUtc={expectedUpdatedUtc}` | `Promise<DynamicModuleRemoval>` | `apps/tenant-runtime/src/api.ts:4197` |
| `deleteTenantAsset` | **DELETE** `/api/assets/{assetId}` | `Promise<TenantAssetMutation>` | `apps/tenant-runtime/src/api.ts:5362` |
| `detachFile` | **DELETE** `/api/modules/files/{recordId}/attachments/{attachmentId}` | `Promise<FileMutation>` | `apps/tenant-runtime/src/api.ts:2303` |
| `downloadConversationAttachment` | **GET** `/api/modules/conversations/{recordId}/messages/{messageId}/attachments/{fileId}/content` | `Promise<Blob>` | `apps/tenant-runtime/src/api.ts:2436` |
| `downloadFileContent` | **GET** `/api/modules/files/{recordId}/content` | `Promise<Blob>` | `apps/tenant-runtime/src/api.ts:2429` |
| `downloadFileVersionContent` | **GET** `/api/modules/files/{recordId}/versions/{version}/content` | `Promise<Blob>` | `apps/tenant-runtime/src/api.ts:2421` |
| `downloadNativeMessageAttachment` | **GET** `/api/tenant/native-message-attachments/{recordId}/content` | `Promise<Blob>` | `apps/tenant-runtime/src/api.ts:3314` |
| `editKnowledgeQuestion` | Delegates through `mutateKnowledgeQuestion` | `Promise<KnowledgeQuestionMutation>` | `apps/tenant-runtime/src/api.ts:4687` |
| `executeRuntimeLegoAction` | **POST** `/api/runtime/lego/actions` | `Promise<LegoActionBrokerResult>` | `apps/tenant-runtime/src/api.ts:5119` |
| `exportChecklistRuns` | **GET** ``/api/modules/checklists-signoffs/export${suffix ? `?{suffix}` : ""}`` | `Promise<ModuleExportFile>` | `apps/tenant-runtime/src/api.ts:1666` |
| `exportContacts` | **GET** `/api/modules/contacts/export?{value}` | `Promise<ContactExportFile>` | `apps/tenant-runtime/src/api.ts:1161` |
| `exportDynamicRecords` | **GET** ``/api/modules/dynamic/{moduleKey}/export${suffix ? `?{suffix}` : ""}`` | `Promise<ModuleExportFile>` | `apps/tenant-runtime/src/api.ts:4143` |
| `exportReservations` | **GET** `/api/modules/reservations/export?{query}` | `Promise<ModuleExportFile>` | `apps/tenant-runtime/src/api.ts:1841` |
| `exportWorkOrders` | **GET** ``/api/modules/work-orders/export${suffix ? `?{suffix}` : ""}`` | `Promise<ModuleExportFile>` | `apps/tenant-runtime/src/api.ts:1469` |
| `findTenantPublishedStylesheet` | Delegates through `isCanonicalPublicAssetUrl, listTenantAssetsWithRouting` | `Promise<TenantAssetList["items"][number]|undefined>` | `apps/tenant-runtime/src/api.ts:5325` |
| `getActiveTenantActor` | Local/session helper | `{ readonly saasAppId: string; readonly appAccountId: string; readonly userId: string } | null` | `apps/tenant-runtime/src/api.ts:611` |
| `getActiveWorkplace` | **GET** `/api/modules/active-workplace/{activeWorkplaceId}` | `Promise<ActiveWorkplaceDetail>` | `apps/tenant-runtime/src/api.ts:3716` |
| `getActiveWorkplaceParticipantCatalog` | **GET** `/api/modules/active-workplace/{activeWorkplaceId}/participants/catalog` | `Promise<ActiveWorkplaceParticipantCatalog>` | `apps/tenant-runtime/src/api.ts:3763` |
| `getActiveWorkplacePlayback` | **GET** `/api/modules/active-workplace/{activeWorkplaceId}/playback?${new URLSearchParams({ at: asOfUtc })}` | `Promise<ActiveWorkplacePlayback>` | `apps/tenant-runtime/src/api.ts:3822` |
| `getAiInsight` | **GET** `/api/modules/ai-insights/{id}` | `Promise<AiInsightDetail>` | `apps/tenant-runtime/src/api.ts:4020` |
| `getAiInsightProducerSettings` | **GET** `aiInsightSettingsPath()` | `Promise<AiInsightProducerSettings>` | `apps/tenant-runtime/src/api.ts:4047` |
| `getCalendarEvent` | **GET** `/api/modules/calendar/{recordId}` | `Promise<CalendarEventDetail>` | `apps/tenant-runtime/src/api.ts:2120` |
| `getChatRoom` | **GET** ``/api/modules/chat-rooms/{recordId}${history ? `?{value}` : ""}`` | `Promise<ChatRoomDetail>` | `apps/tenant-runtime/src/api.ts:2952` |
| `getChatRoomMemberLookup` | **GET** `/api/modules/chat-rooms/{recordId}/members/lookup?{query}` | `Promise<ChatRoomMemberLookup>` | `apps/tenant-runtime/src/api.ts:3066` |
| `getChecklistExportCapability` | **GET** `/api/modules/checklists-signoffs/export/capability` | `Promise<ModuleExportCapability>` | `apps/tenant-runtime/src/api.ts:1664` |
| `getChecklistRun` | **GET** `/api/modules/checklists-signoffs/runs/{checklistRunId}` | `Promise<ChecklistRunDetail>` | `apps/tenant-runtime/src/api.ts:1696` |
| `getChecklistTemplate` | **GET** `/api/modules/checklists-signoffs/templates/{checklistTemplateId}` | `Promise<ChecklistTemplateDetail>` | `apps/tenant-runtime/src/api.ts:1622` |
| `getCompanyNews` | **GET** `/api/modules/company-news/{recordId}` | `Promise<CompanyNewsDetail>` | `apps/tenant-runtime/src/api.ts:2678` |
| `getCompanyNewsLegoCatalog` | **GET** `/api/modules/company-news/schema` | `Promise<CompanyNewsLegoCatalog>` | `apps/tenant-runtime/src/api.ts:2636` |
| `getCompanyNewsLegoLookup` | **GET** `/api/modules/company-news/lookups/{lookupId}?{query}` | `Promise<CompanyNewsLegoLookupPage>` | `apps/tenant-runtime/src/api.ts:2650` |
| `getContact` | **GET** `/api/modules/contacts/{recordId}` | `Promise<ContactDetail>` | `apps/tenant-runtime/src/api.ts:1276` |
| `getContactCreateVisibilityOptions` | **GET** `/api/modules/contacts/create-visibility-options` | `Promise<ContactCreateVisibilityOptions>` | `apps/tenant-runtime/src/api.ts:1308` |
| `getContactExportCapability` | **GET** `/api/modules/contacts/export/capability` | `Promise<ContactExportCapability>` | `apps/tenant-runtime/src/api.ts:1159` |
| `getContactsLegoCatalog` | **GET** `/api/modules/contacts/schema` | `Promise<ContactLegoCatalog>` | `apps/tenant-runtime/src/api.ts:1229` |
| `getContactsLegoLookup` | **GET** `/api/modules/contacts/lookups/{normalizedLookupId}?{query}` | `Promise<ContactLegoLookupPage>` | `apps/tenant-runtime/src/api.ts:1242` |
| `getContextualKnowledge` | **GET** `/api/modules/record-graph/{recordId}/knowledge/candidates?${new URLSearchParams({ requireAiRead: String(requireAiRead), maxCandidates: String(maxCandidates) })}` | `Promise<ContextualKnowledgeResponse>` | `apps/tenant-runtime/src/api.ts:3586` |
| `getConversation` | **GET** `/api/modules/conversations/{recordId}?{query}` | `Promise<ConversationDetail>` | `apps/tenant-runtime/src/api.ts:2510` |
| `getConversationsLegoCatalog` | **GET** `/api/modules/conversations/lego-catalog` | `Promise<ConversationsLegoCatalog>` | `apps/tenant-runtime/src/api.ts:2449` |
| `getConversationsLegoPresentation` | **GET** `/api/modules/conversations/lego-presentation?{query}` | `Promise<ConversationsLegoPresentation>` | `apps/tenant-runtime/src/api.ts:2459` |
| `getDirectConversationScope` | **GET** ``/api/modules/conversations/direct/scope${query.size ? `?{query}` : ""}`` | `Promise<import("@buildwithhq/module-sdk").DirectConversationScope>` | `apps/tenant-runtime/src/api.ts:2572` |
| `getDiscussionBoard` | **GET** `/api/modules/discussion-boards/{recordId}?{query}` | `Promise<DiscussionBoardDetail>` | `apps/tenant-runtime/src/api.ts:3122` |
| `getDiscussionTopic` | **GET** `/api/modules/discussion-boards/topics/{recordId}{suffix}` | `Promise<DiscussionTopicDetail>` | `apps/tenant-runtime/src/api.ts:3185` |
| `getDynamicModuleRecord` | **GET** `/api/modules/dynamic/{moduleKey}/{recordId}` | `Promise<DynamicModuleDetail>` | `apps/tenant-runtime/src/api.ts:4155` |
| `getDynamicModuleSchema` | **GET** `/api/modules/dynamic/{moduleKey}/schema` | `Promise<DynamicModuleSchema>` | `apps/tenant-runtime/src/api.ts:4103` |
| `getDynamicRecordExportCapability` | **GET** `/api/modules/dynamic/{moduleKey}/export/capability` | `Promise<ModuleExportCapability>` | `apps/tenant-runtime/src/api.ts:4141` |
| `getFavorite` | **GET** `/api/modules/favorites/{recordId}` | `Promise<FavoriteDetail>` | `apps/tenant-runtime/src/api.ts:3447` |
| `getFavoritesLegoCatalog` | **GET** `/api/modules/favorites/schema` | `Promise<FavoritesLegoCatalog>` | `apps/tenant-runtime/src/api.ts:3417` |
| `getFavoritesLegoPresentation` | **GET** `/api/modules/favorites/presentation{suffix}` | `Promise<DataGridPresentation>` | `apps/tenant-runtime/src/api.ts:3425` |
| `getFavoriteState` | **GET** `/api/modules/favorites/{recordId}/state` | `Promise<FavoriteMutation>` | `apps/tenant-runtime/src/api.ts:3459` |
| `getFile` | **GET** `/api/modules/files/{recordId}` | `Promise<FileDetail>` | `apps/tenant-runtime/src/api.ts:2203` |
| `getInboxLegoCatalog` | **GET** `/api/inbox/lego-catalog` | `Promise<InboxLegoCatalog>` | `apps/tenant-runtime/src/api.ts:3885` |
| `getInboxLegoPresentation` | **GET** `/api/inbox/lego-presentation?{query}` | `Promise<InboxLegoPresentation>` | `apps/tenant-runtime/src/api.ts:3895` |
| `getKnowledgeArticle` | **GET** `/api/modules/knowledge-articles/{recordId}` | `Promise<KnowledgeArticleDetail>` | `apps/tenant-runtime/src/api.ts:4273` |
| `getKnowledgeAssignmentLookup` | **GET** `/api/modules/knowledge-core/assignment-lookup?{query}` | `Promise<KnowledgeAssignmentLookup>` | `apps/tenant-runtime/src/api.ts:4567` |
| `getKnowledgeCore` | **GET** `/api/modules/knowledge-core/{recordId}` | `Promise<KnowledgeCoreDetail>` | `apps/tenant-runtime/src/api.ts:4347` |
| `getKnowledgeCoreOwners` | **GET** `/api/modules/knowledge-core/{recordId}/owners` | `Promise<KnowledgeOwners>` | `apps/tenant-runtime/src/api.ts:4505` |
| `getKnowledgeCoreRevisions` | **GET** `/api/modules/knowledge-core/{recordId}/revisions` | `Promise<KnowledgeRevisionHistory>` | `apps/tenant-runtime/src/api.ts:4414` |
| `getKnowledgeFeedback` | **GET** `/api/modules/knowledge-core/{recordId}/feedback` | `Promise<KnowledgeFeedbackSummary>` | `apps/tenant-runtime/src/api.ts:4814` |
| `getKnowledgeGaps` | **GET** `/api/modules/knowledge-core/gaps?{query}` | `Promise<KnowledgeGapList>` | `apps/tenant-runtime/src/api.ts:4780` |
| `getKnowledgeHealth` | **GET** `/api/modules/knowledge-core/health` | `Promise<KnowledgeHealth>` | `apps/tenant-runtime/src/api.ts:4582` |
| `getMailReaderMessage` | **GET** `/api/modules/mail-reader/{recordId}` | `Promise<MailReaderMessageDetail>` | `apps/tenant-runtime/src/api.ts:3299` |
| `getModuleCapabilities` | **GET** `/api/modules/{moduleKey}/capabilities{query}` | `Promise<TenantModuleCapabilities>` | `apps/tenant-runtime/src/api.ts:1773` |
| `getNativeRecordPages` | **GET** `/api/runtime/record-scope/records/{recordId}/pages` | `Promise<NativeRecordPagesResponse>` | `apps/tenant-runtime/src/api.ts:2752` |
| `getNotification` | **GET** `/api/modules/notifications/{id}` | `Promise<NotificationDetail>` | `apps/tenant-runtime/src/api.ts:3961` |
| `getNotificationsLegoCatalog` | **GET** `/api/modules/notifications/lego-catalog` | `Promise<NotificationsLegoCatalog>` | `apps/tenant-runtime/src/api.ts:3911` |
| `getNotificationsLegoPresentation` | **GET** `/api/modules/notifications/lego-presentation?{query}` | `Promise<NotificationsLegoPresentation>` | `apps/tenant-runtime/src/api.ts:3921` |
| `getPageRevision` | **GET** `` `${pageRevisionBase(pageKey)}/${pageRevisionId(pageHistoryId)}` `` | `Promise<PageRevisionSnapshot>` | `apps/tenant-runtime/src/api.ts:5176` |
| `getRecordActivity` | **GET** `/api/modules/record-activity/{recordId}?{query}` | `Promise<RecordActivityResponse>` | `apps/tenant-runtime/src/api.ts:3653` |
| `getRecordCreateScopeChoices` | **GET** `/api/runtime/record-scope/create-roles` | `Promise<RecordCreateScopeChoices>` | `apps/tenant-runtime/src/api.ts:2716` |
| `getRecordCurrentScope` | **GET** `/api/runtime/record-scope/records/{recordId}` | `Promise<RecordCurrentScope>` | `apps/tenant-runtime/src/api.ts:2759` |
| `getRecordGraph` | **GET** `/api/modules/record-graph/{recordId}?${new URLSearchParams({ maxDepth: String(Math.min(5, Math.max(1, Math.trunc(maxDepth)))), maxNodes: String(Math.min(200, Math.max(2, Math.trunc(maxNodes)))) })}` | `Promise<RecordGraphResponse>` | `apps/tenant-runtime/src/api.ts:3524` |
| `getRelatedKnowledge` | **GET** `/api/modules/record-graph/{recordId}/knowledge?${new URLSearchParams({ maxItems: String(maxItems) })}` | `Promise<RelatedKnowledgeResponse>` | `apps/tenant-runtime/src/api.ts:3573` |
| `getReservation` | **GET** `/api/modules/reservations/{recordId}` | `Promise<ReservationDetail>` | `apps/tenant-runtime/src/api.ts:1886` |
| `getReservationExportCapability` | **GET** `/api/modules/reservations/export/capability` | `Promise<ModuleExportCapability>` | `apps/tenant-runtime/src/api.ts:1839` |
| `getTenantAccessToken` | Local/session helper | `string | null` | `apps/tenant-runtime/src/api.ts:607` |
| `getTenantFeatureReadiness` | **GET** `/api/runtime/feature-readiness` | `Promise<TenantFeatureReadinessSnapshot>` | `apps/tenant-runtime/src/api.ts:969` |
| `getTenantPageDrift` | **GET** `pageAdoptionBase(pageKey)` | `Promise<TenantPageDrift>` | `apps/tenant-runtime/src/api.ts:5253` |
| `getTenantPaymentMethod` | **GET** `/api/modules/payments/methods/{paymentMethodId}` | `Promise<TenantPaymentMethod>` | `apps/tenant-runtime/src/api.ts:2009` |
| `getTenantPaymentSettings` | **GET** `/api/modules/payments/settings` | `Promise<TenantPaymentSettings>` | `apps/tenant-runtime/src/api.ts:1950` |
| `getTenantRecordPayments` | **GET** `/api/modules/payments/records/{recordId}` | `Promise<TenantRecordPaymentSummary>` | `apps/tenant-runtime/src/api.ts:2039` |
| `getTenantSessionEpoch` | Local/session helper | `number` | `apps/tenant-runtime/src/api.ts:609` |
| `getWebLink` | **GET** `/api/modules/web-links/{recordId}` | `Promise<WebLinkDetail>` | `apps/tenant-runtime/src/api.ts:2871` |
| `getWorkOrder` | **GET** `/api/modules/work-orders/{recordId}` | `Promise<WorkOrderDetail>` | `apps/tenant-runtime/src/api.ts:1552` |
| `getWorkOrderExportCapability` | **GET** `/api/modules/work-orders/export/capability` | `Promise<ModuleExportCapability>` | `apps/tenant-runtime/src/api.ts:1467` |
| `getWorkOrderLegoCatalog` | **GET** `/api/modules/work-orders/schema` | `Promise<WorkOrderLegoCatalog>` | `apps/tenant-runtime/src/api.ts:1482` |
| `getWorkOrderLegoLookup` | **GET** `/api/modules/work-orders/lookups/{normalized}?{query}` | `Promise<WorkOrderLegoLookupPage>` | `apps/tenant-runtime/src/api.ts:1494` |
| `getWorkOrderStatusTransitions` | **GET** `/api/modules/work-orders/{recordId}/status-transitions` | `Promise<WorkOrderStatusTransitions>` | `apps/tenant-runtime/src/api.ts:1533` |
| `isTenantFeatureReady` | Local/session helper | `boolean` | `apps/tenant-runtime/src/api.ts:987` |
| `linkKnowledgeToRecord` | **PUT** `/api/modules/record-graph/{recordId}/knowledge` | `Promise<KnowledgeRelationMutation>` | `apps/tenant-runtime/src/api.ts:3600` |
| `listActiveWorkplaces` | **GET** `/api/modules/active-workplace?{query}` | `Promise<ActiveWorkplaceList>` | `apps/tenant-runtime/src/api.ts:3691` |
| `listAiInsights` | **GET** `/api/modules/ai-insights?{query}` | `Promise<AiInsightList>` | `apps/tenant-runtime/src/api.ts:3998` |
| `listCalendarEvents` | **GET** `/api/modules/calendar?{query}` | `Promise<CalendarEventList>` | `apps/tenant-runtime/src/api.ts:2091` |
| `listChatRooms` | **GET** `/api/modules/chat-rooms?{query}` | `Promise<ChatRoomsList>` | `apps/tenant-runtime/src/api.ts:2931` |
| `listChecklistRuns` | **GET** `/api/modules/checklists-signoffs/runs?{query}` | `Promise<ChecklistRunList>` | `apps/tenant-runtime/src/api.ts:1677` |
| `listChecklistTemplates` | **GET** `/api/modules/checklists-signoffs/templates` | `Promise<ChecklistTemplateList>` | `apps/tenant-runtime/src/api.ts:1613` |
| `listCompanyNews` | **GET** `/api/modules/company-news?{query}` | `Promise<CompanyNewsList>` | `apps/tenant-runtime/src/api.ts:2612` |
| `listContacts` | **GET** `/api/modules/contacts?{query}`
**GET** `/api/modules/contacts/count?{countQuery}` | `Promise<ContactList>` | `apps/tenant-runtime/src/api.ts:1181` |
| `listConversations` | **GET** `/api/modules/conversations?{query}` | `Promise<ConversationList>` | `apps/tenant-runtime/src/api.ts:2478` |
| `listDiscussionBoards` | **GET** `/api/modules/discussion-boards?{query}` | `Promise<DiscussionBoardsList>` | `apps/tenant-runtime/src/api.ts:3099` |
| `listDynamicModuleRecords` | **GET** `/api/modules/dynamic/{moduleKey}?{q}` | `Promise<DynamicModuleList>` | `apps/tenant-runtime/src/api.ts:4112` |
| `listDynamicModuleSchemas` | **GET** `/api/modules/dynamic` | `Promise<DynamicModuleCatalog>` | `apps/tenant-runtime/src/api.ts:4095` |
| `listFavorites` | **GET** `/api/modules/favorites?{query}` | `Promise<FavoritesList>` | `apps/tenant-runtime/src/api.ts:3394` |
| `listFileComments` | **GET** `/api/modules/files/{recordId}/comments?{value}` | `Promise<FileCommentPage>` | `apps/tenant-runtime/src/api.ts:2333` |
| `listFiles` | **GET** `/api/modules/files?{query}` | `Promise<FileList>` | `apps/tenant-runtime/src/api.ts:2177` |
| `listFileVersions` | **GET** `/api/modules/files/{recordId}/versions?{value}` | `Promise<FileVersionPage>` | `apps/tenant-runtime/src/api.ts:2406` |
| `listKnowledgeArticles` | **GET** `/api/modules/knowledge-articles?{query}` | `Promise<KnowledgeArticlesList>` | `apps/tenant-runtime/src/api.ts:4249` |
| `listKnowledgeCore` | **GET** `/api/modules/knowledge-core?{query}` | `Promise<KnowledgeCoreList>` | `apps/tenant-runtime/src/api.ts:4322` |
| `listKnowledgeCoreCollections` | **GET** `/api/modules/knowledge-core/collections` | `Promise<KnowledgeCollections>` | `apps/tenant-runtime/src/api.ts:4447` |
| `listKnowledgeFeedbackComments` | **GET** `/api/modules/knowledge-core/{recordId}/feedback/comments?{query}` | `Promise<KnowledgeFeedbackCommentPage>` | `apps/tenant-runtime/src/api.ts:4828` |
| `listKnowledgeQuestions` | **GET** `/api/modules/knowledge-core/questions?{query}` | `Promise<KnowledgeQuestionList>` | `apps/tenant-runtime/src/api.ts:4655` |
| `listKnowledgeReviews` | **GET** `/api/modules/knowledge-core/reviews` | `Promise<KnowledgeReviewList>` | `apps/tenant-runtime/src/api.ts:4557` |
| `listMailReaderMailboxes` | **GET** `/api/modules/mail-reader/mailboxes` | `inferred` | `apps/tenant-runtime/src/api.ts:3374` |
| `listMailReaderMessages` | **GET** `/api/modules/mail-reader?{query}` | `Promise<MailReaderList>` | `apps/tenant-runtime/src/api.ts:3276` |
| `listNotifications` | **GET** `/api/modules/notifications?{query}` | `Promise<NotificationList>` | `apps/tenant-runtime/src/api.ts:3940` |
| `listPageRevisions` | **GET** `` `${pageRevisionBase(pageKey)}?limit=${limit}` `` | `Promise<readonly PageRevision[]>` | `apps/tenant-runtime/src/api.ts:5162` |
| `listRecordCreateRoles` | Delegates through `getRecordCreateScopeChoices` | `Promise<readonly RecordCreateRoleOption[]>` | `apps/tenant-runtime/src/api.ts:2741` |
| `listRecordTypes` | **GET** `/api/runtime/record-types` | `Promise<RecordTypeList>` | `apps/tenant-runtime/src/api.ts:1140` |
| `listReservationAssignees` | **GET** `/api/modules/reservations/assignees?{query}` | `Promise<ReservationAssigneeLookup>` | `apps/tenant-runtime/src/api.ts:1816` |
| `listReservationProducts` | **GET** `/api/modules/reservations/products?includeInactive={includeInactive}` | `Promise<ReservationProductList>` | `apps/tenant-runtime/src/api.ts:1797` |
| `listReservations` | **GET** `/api/modules/reservations?{query}` | `Promise<ReservationList>` | `apps/tenant-runtime/src/api.ts:1855` |
| `listTenantAssets` | Delegates through `listTenantAssetsWithRouting` | `Promise<TenantAssetList>` | `apps/tenant-runtime/src/api.ts:5322` |
| `listTenantInboundEndpoints` | **GET** `/api/account-admin/inbound-endpoints` | `inferred` | `apps/tenant-runtime/src/api.ts:4641` |
| `listTenantPageDrift` | **GET** `/api/runtime/pages/drift` | `Promise<readonly TenantPageDrift[]>` | `apps/tenant-runtime/src/api.ts:5261` |
| `listTenantPaymentAttention` | **GET** `/api/modules/payments/attention{query}` | `Promise<TenantPaymentAttentionList>` | `apps/tenant-runtime/src/api.ts:2071` |
| `listTenantPaymentMethods` | **GET** `/api/modules/payments/methods{query}` | `Promise<TenantPaymentMethodList>` | `apps/tenant-runtime/src/api.ts:1987` |
| `listTenantSessions` | **GET** `/api/auth/tenant/sessions` | `Promise<TenantSecuritySessionsSnapshot>` | `apps/tenant-runtime/src/api.ts:1093` |
| `listUnownedKnowledgeCore` | **GET** `/api/modules/knowledge-core/unowned?{query}` | `Promise<KnowledgeCoreList>` | `apps/tenant-runtime/src/api.ts:4540` |
| `listWebLinks` | **GET** `/api/modules/web-links?{query}` | `Promise<WebLinksList>` | `apps/tenant-runtime/src/api.ts:2850` |
| `listWorkOrders` | **GET** `/api/modules/work-orders?{query}` | `Promise<WorkOrderList>` | `apps/tenant-runtime/src/api.ts:1437` |
| `loadAppVocabulary` | **GET** `/api/runtime/vocabulary` | `Promise<AppVocabulary>` | `apps/tenant-runtime/src/api.ts:5448` |
| `loadRuntimeBootstrap` | **GET** `/api/runtime/bootstrap/{pageKey}` | `Promise<RuntimeBootstrap>` | `apps/tenant-runtime/src/api.ts:5006` |
| `loadRuntimeBootstrapBySlug` | **GET** `/api/runtime/route?{value}` | `Promise<RuntimeBootstrap>` | `apps/tenant-runtime/src/api.ts:5033` |
| `loadRuntimeDataBinding` | **GET** `/api/runtime/data/{bindingKey}{value}` | `Promise<RuntimeDataBinding>` | `apps/tenant-runtime/src/api.ts:5078` |
| `loadRuntimeDataBindings` | **POST** `/api/runtime/data/batch` | `Promise<RuntimeDataBindingBatch>` | `apps/tenant-runtime/src/api.ts:5095` |
| `loadTenantAssetContent` | **GET** `url` | `Promise<Blob>` | `apps/tenant-runtime/src/api.ts:5379` |
| `loginTenant` | Delegates through `tenantAuthenticationRequest` | `Promise<TenantLoginResult>` | `apps/tenant-runtime/src/api.ts:4868` |
| `logoutAllTenantSessions` | **POST** `/api/auth/tenant/logout-all` | `Promise<void>` | `apps/tenant-runtime/src/api.ts:1106` |
| `logoutTenant` | Delegates through `clearTenantSession, logoutTenantCore, markLocalSignOut, withTenantSessionCookieLock` | `Promise<void>` | `apps/tenant-runtime/src/api.ts:1080` |
| `markChatRoomRead` | **PUT** `/api/modules/chat-rooms/{recordId}/read` | `Promise<ChatRoomMutation>` | `apps/tenant-runtime/src/api.ts:3075` |
| `onTenantSessionExpired` | Local/session helper | `(() => void)` | `apps/tenant-runtime/src/api.ts:859` |
| `parseAppVocabulary` | Delegates through `object, vocabularyText` | `AppVocabulary` | `apps/tenant-runtime/src/api.ts:5420` |
| `parseTenantMfaStep` | Delegates through `invalidAuthenticationResponse, isSafeDestinationHint` | `TenantMfaRequired` | `apps/tenant-runtime/src/api.ts:500` |
| `postChatMessage` | **POST** `/api/modules/chat-rooms/{recordId}/messages` | `Promise<ChatRoomMutation>` | `apps/tenant-runtime/src/api.ts:2999` |
| `postConversationMessage` | **POST** `/api/modules/conversations/{recordId}/messages` | `Promise<ConversationMutation>` | `apps/tenant-runtime/src/api.ts:2558` |
| `postDiscussionReply` | **POST** `/api/modules/discussion-boards/topics/{topicRecordId}/posts` | `Promise<DiscussionMutation>` | `apps/tenant-runtime/src/api.ts:3228` |
| `publishKnowledgeCore` | **POST** `/api/modules/knowledge-core/{recordId}/publish` | `Promise<KnowledgeCoreMutation>` | `apps/tenant-runtime/src/api.ts:4382` |
| `purchaseReservation` | **POST** `/api/modules/reservations/purchase` | `Promise<ReservationMutation>` | `apps/tenant-runtime/src/api.ts:1896` |
| `reassignKnowledgeReview` | **POST** `/api/modules/knowledge-core/reviews/{reviewCycleId}/reassign` | `Promise<KnowledgeReviewMutation>` | `apps/tenant-runtime/src/api.ts:4625` |
| `recordActiveWorkplaceActivity` | **POST** `/api/modules/active-workplace/{activeWorkplaceId}/activity` | `Promise<ActiveWorkplaceMutation>` | `apps/tenant-runtime/src/api.ts:3799` |
| `recordKnowledgeFeedback` | **POST** `/api/modules/knowledge-core/{recordId}/feedback` | `Promise<KnowledgeFeedbackMutation>` | `apps/tenant-runtime/src/api.ts:4797` |
| `refreshActiveWorkplaceGraph` | **POST** `/api/modules/active-workplace/{activeWorkplaceId}/graph/refresh` | `Promise<ActiveWorkplaceMutation>` | `apps/tenant-runtime/src/api.ts:3811` |
| `refreshTenantSession` | Delegates through `expireTenantSession, hasLocalSignOut, refreshTenantSessionCore` | `Promise<TenantRefreshSuccess>` | `apps/tenant-runtime/src/api.ts:839` |
| `registerTenantPaymentMethod` | **POST** `/api/modules/payments/methods` | `Promise<TenantPaymentMutation>` | `apps/tenant-runtime/src/api.ts:1999` |
| `releasePageEditLock` | **DELETE** `/api/runtime/pages/{value}/edit-lock` | `Promise<PageEditLockRelease>` | `apps/tenant-runtime/src/api.ts:5238` |
| `removeActiveWorkplaceParticipant` | **DELETE** `/api/modules/active-workplace/{activeWorkplaceId}/participants/{participantId}` | `Promise<ActiveWorkplaceMutation>` | `apps/tenant-runtime/src/api.ts:3787` |
| `removeCalendarEvent` | **DELETE** `/api/modules/calendar/{recordId}?expectedUpdatedUtc={expectedUpdatedUtc}` | `Promise<CalendarRemoval>` | `apps/tenant-runtime/src/api.ts:2152` |
| `removeChatMessage` | **DELETE** `/api/modules/chat-rooms/{recordId}/messages/{chatMessageId}?{query}` | `Promise<ChatRoomMutation>` | `apps/tenant-runtime/src/api.ts:3024` |
| `removeChatRoom` | **DELETE** `/api/modules/chat-rooms/{recordId}` | `Promise<ChatRoomRemoval>` | `apps/tenant-runtime/src/api.ts:2988` |
| `removeChecklistProof` | **DELETE** `/api/modules/checklists-signoffs/proof/{checklistItemEvidenceId}` | `Promise<ChecklistMutation>` | `apps/tenant-runtime/src/api.ts:1735` |
| `removeChecklistTemplate` | **DELETE** `/api/modules/checklists-signoffs/templates/{checklistTemplateId}` | `Promise<ChecklistTemplateRemoval>` | `apps/tenant-runtime/src/api.ts:1653` |
| `removeCompanyNews` | **DELETE** `/api/modules/company-news/{recordId}?expectedUpdatedUtc={expectedUpdatedUtc}` | `Promise<CompanyNewsRemoval>` | `apps/tenant-runtime/src/api.ts:2839` |
| `removeContact` | **DELETE** `/api/modules/contacts/{recordId}?expectedUpdatedUtc={expectedUpdatedUtc}` | `Promise<ContactRemoval>` | `apps/tenant-runtime/src/api.ts:1415` |
| `removeConversation` | **DELETE** `/api/modules/conversations/{recordId}?expectedUpdatedUtc={expectedUpdatedUtc}` | `Promise<ConversationRemoval>` | `apps/tenant-runtime/src/api.ts:2827` |
| `removeDiscussionBoard` | **DELETE** `/api/modules/discussion-boards/{recordId}` | `Promise<DiscussionBoardRemoval>` | `apps/tenant-runtime/src/api.ts:3162` |
| `removeDiscussionPost` | **DELETE** `/api/modules/discussion-boards/posts/{recordId}` | `Promise<DiscussionPostRemoval>` | `apps/tenant-runtime/src/api.ts:3252` |
| `removeDiscussionTopic` | **DELETE** `/api/modules/discussion-boards/topics/{recordId}` | `Promise<DiscussionTopicRemoval>` | `apps/tenant-runtime/src/api.ts:3217` |
| `removeFile` | **DELETE** `/api/modules/files/{recordId}?{value}` | `Promise<FileRemoval>` | `apps/tenant-runtime/src/api.ts:2279` |
| `removeFileComment` | **DELETE** `/api/modules/files/{recordId}/comments/{commentId}` | `Promise<FileCommentRemoval>` | `apps/tenant-runtime/src/api.ts:2374` |
| `removeKnowledgeCoreCollectionItem` | **DELETE** `/api/modules/knowledge-core/collections/{collectionId}/items/{recordId}` | `Promise<KnowledgeCollectionMutation>` | `apps/tenant-runtime/src/api.ts:4493` |
| `removeKnowledgeCoreOwner` | **DELETE** `/api/modules/knowledge-core/owners/{knowledgeOwnerId}` | `Promise<KnowledgeOwnerMutation>` | `apps/tenant-runtime/src/api.ts:4529` |
| `removeRecordGraphRelation` | **DELETE** `/api/modules/record-graph/relations/{recordRelationId}` | `Promise<RecordGraphMutation>` | `apps/tenant-runtime/src/api.ts:3550` |
| `removeWebLink` | **DELETE** `/api/modules/web-links/{recordId}?expectedUpdatedUtc={expectedUpdatedUtc}` | `Promise<WebLinkRemoval>` | `apps/tenant-runtime/src/api.ts:2906` |
| `removeWorkOrder` | **DELETE** `/api/modules/work-orders/{recordId}?expectedUpdatedUtc={expectedUpdatedUtc}` | `Promise<WorkOrderRemoval>` | `apps/tenant-runtime/src/api.ts:1581` |
| `requestTenantEmailChange` | Delegates through `accountSecurityPost, canonicalReceiptObject, invalidAccountSecurityResponse` | `Promise<void>` | `apps/tenant-runtime/src/api.ts:4999` |
| `requestTenantPasswordReset` | Delegates through `canonicalReceiptObject, invalidPublicAccountResponse, publicAccountPost` | `Promise<void>` | `apps/tenant-runtime/src/api.ts:4941` |
| `rescheduleReservation` | **PUT** `/api/modules/reservations/{recordId}/schedule` | `Promise<ReservationMutation>` | `apps/tenant-runtime/src/api.ts:1915` |
| `resendTenantMfaCode` | **POST** `/api/auth/tenant/mfa/resend` | `Promise<TenantMfaResendReceipt>` | `apps/tenant-runtime/src/api.ts:4897` |
| `resolveTenantPaymentAttention` | **POST** `/api/modules/payments/records/{recordId}/charges/{chargeIntentId}/attention` | `Promise<TenantPaymentAttentionReceipt>` | `apps/tenant-runtime/src/api.ts:2079` |
| `restoreKnowledgeCoreRevision` | **POST** `/api/modules/knowledge-core/{recordId}/restore` | `Promise<KnowledgeCoreMutation>` | `apps/tenant-runtime/src/api.ts:4426` |
| `restorePageRevision` | **POST** `` `${pageRevisionBase(pageKey)}/${pageRevisionId(pageHistoryId)}/restore` `` | `Promise<PageRestoreResult>` | `apps/tenant-runtime/src/api.ts:5204` |
| `restoreTenantSession` | Delegates through `refreshTenantSession` | `Promise<TenantRefreshSuccess>` | `apps/tenant-runtime/src/api.ts:856` |
| `revealContactSecureField` | **POST** `/api/modules/contacts/{recordId}/secure-fields/{fieldDefinitionId}/reveal` | `Promise<ContactSecureFieldReveal>` | `apps/tenant-runtime/src/api.ts:1344` |
| `revokeTenantPaymentMethod` | **DELETE** `/api/modules/payments/methods/{paymentMethodId}` | `Promise<TenantPaymentMutation>` | `apps/tenant-runtime/src/api.ts:2029` |
| `revokeTenantSession` | **DELETE** `/api/auth/tenant/sessions/{sessionId}` | `Promise<void>` | `apps/tenant-runtime/src/api.ts:1099` |
| `saveAiInsightDirective` | **UNKNOWN** `` directiveId           ? `${aiInsightSettingsPath()}/directives/${encodeURIComponent(directiveId)}`           : `${aiInsightSettingsPath()}/directives` `` | `Promise<AiInsightProducerSettings>` | `apps/tenant-runtime/src/api.ts:4065` |
| `saveAiInsightProducerSettings` | **PUT** `aiInsightSettingsPath()` | `Promise<AiInsightProducerSettings>` | `apps/tenant-runtime/src/api.ts:4053` |
| `saveReservationProduct` | **POST** `/api/modules/reservations/products` | `Promise<ReservationMutation>` | `apps/tenant-runtime/src/api.ts:1807` |
| `saveTenantPage` | **POST** `` `${pageRevisionBase(pageKey)}/save` `` | `Promise<PageSaveReport>` | `apps/tenant-runtime/src/api.ts:5188` |
| `searchGlobalRecords` | **GET** `/api/modules/global-search?{parameters}`
**GET** `/api/modules/global-search/count?{countQuery}` | `Promise<GlobalSearchResponse>` | `apps/tenant-runtime/src/api.ts:3836` |
| `searchRecordActivity` | **GET** `/api/modules/record-activity/records?{query}` | `Promise<RecordActivitySearchResponse>` | `apps/tenant-runtime/src/api.ts:3624` |
| `searchRecordGraph` | **GET** `/api/modules/record-graph/records?{query}` | `Promise<RecordGraphSearchResponse>` | `apps/tenant-runtime/src/api.ts:3496` |
| `sendDirectConversation` | **POST** `/api/modules/conversations/direct` | `Promise<ConversationMutation>` | `apps/tenant-runtime/src/api.ts:2585` |
| `setActiveWorkplaceStatus` | **POST** `/api/modules/active-workplace/{activeWorkplaceId}/status` | `Promise<ActiveWorkplaceMutation>` | `apps/tenant-runtime/src/api.ts:3751` |
| `setAiInsightStarterDirective` | **PUT** `` `${aiInsightSettingsPath()}/starters/${encodeURIComponent(directiveId)}` `` | `Promise<AiInsightProducerSettings>` | `apps/tenant-runtime/src/api.ts:4079` |
| `setAiInsightState` | **PUT** `/api/modules/ai-insights/{id}/state` | `Promise<AiInsightState>` | `apps/tenant-runtime/src/api.ts:4032` |
| `setCalendarFavorite` | **PUT** `/api/modules/calendar/{recordId}/favorite` | `Promise<CalendarMutation>` | `apps/tenant-runtime/src/api.ts:2163` |
| `setChatReaction` | **PUT** `/api/modules/chat-rooms/{recordId}/messages/{chatMessageId}/reaction` | `Promise<ChatRoomMutation>` | `apps/tenant-runtime/src/api.ts:3039` |
| `setChatRoomFavorite` | **PUT** `/api/modules/chat-rooms/{recordId}/favorite` | `Promise<ChatRoomMutation>` | `apps/tenant-runtime/src/api.ts:3086` |
| `setChatRoomMember` | **PUT** `/api/modules/chat-rooms/{recordId}/members/{memberUserId}` | `Promise<ChatRoomMutation>` | `apps/tenant-runtime/src/api.ts:3053` |
| `setCompanyNewsFavorite` | **PUT** `/api/modules/company-news/{recordId}/favorite` | `Promise<CompanyNewsMutation>` | `apps/tenant-runtime/src/api.ts:2798` |
| `setCompanyNewsPublished` | **PUT** `/api/modules/company-news/{recordId}/published` | `Promise<CompanyNewsMutation>` | `apps/tenant-runtime/src/api.ts:2812` |
| `setContactFavorite` | **PUT** `/api/modules/contacts/{recordId}/favorite` | `Promise<ContactMutation>` | `apps/tenant-runtime/src/api.ts:1426` |
| `setContactSecureField` | **PUT** `/api/modules/contacts/{recordId}/secure-fields/{fieldDefinitionId}` | `Promise<ContactSecureFieldMutation>` | `apps/tenant-runtime/src/api.ts:1357` |
| `setConversationFavorite` | **PUT** `/api/modules/conversations/{recordId}/favorite` | `Promise<ConversationMutation>` | `apps/tenant-runtime/src/api.ts:2598` |
| `setDefaultTenantPaymentMethod` | **PUT** `/api/modules/payments/methods/{paymentMethodId}/default` | `Promise<TenantPaymentMutation>` | `apps/tenant-runtime/src/api.ts:2019` |
| `setDiscussionFavorite` | **PUT** `/api/modules/discussion-boards/records/{recordId}/favorite` | `Promise<DiscussionMutation>` | `apps/tenant-runtime/src/api.ts:3263` |
| `setDynamicModuleFavorite` | **PUT** `/api/modules/dynamic/{moduleKey}/{recordId}/favorite` | `Promise<DynamicModuleMutation>` | `apps/tenant-runtime/src/api.ts:4210` |
| `setFavorite` | **PUT** `/api/modules/favorites/{recordId}/favorite` | `Promise<FavoriteMutation>` | `apps/tenant-runtime/src/api.ts:3471` |
| `setFileFavorite` | **PUT** `/api/modules/files/{recordId}/favorite` | `Promise<FileMutation>` | `apps/tenant-runtime/src/api.ts:2316` |
| `setGlobalSearchFavorite` | **PUT** `/api/modules/global-search/records/{recordId}/favorite` | `Promise<FavoriteMutation>` | `apps/tenant-runtime/src/api.ts:3872` |
| `setKnowledgeArticleFavorite` | **PUT** `/api/modules/knowledge-articles/{recordId}/favorite` | `Promise<KnowledgeArticleMutation>` | `apps/tenant-runtime/src/api.ts:4308` |
| `setKnowledgeCoreOwner` | **POST** `/api/modules/knowledge-core/{recordId}/owners` | `Promise<KnowledgeOwnerMutation>` | `apps/tenant-runtime/src/api.ts:4517` |
| `setMailReaderCredential` | **PUT** `/api/modules/mail-reader/mailboxes/{mailboxRecordId}/credentials/{purpose}` | `inferred` | `apps/tenant-runtime/src/api.ts:3384` |
| `setMailReaderFavorite` | **PUT** `/api/modules/mail-reader/{recordId}/favorite` | `Promise<MailReaderMutation>` | `apps/tenant-runtime/src/api.ts:3361` |
| `setMailReaderRead` | **PUT** `/api/modules/mail-reader/{recordId}/read` | `Promise<MailReaderMutation>` | `apps/tenant-runtime/src/api.ts:3348` |
| `setNotificationSourceFavorite` | **PUT** `/api/modules/notifications/{id}/source-favorite` | `Promise<NotificationMutation>` | `apps/tenant-runtime/src/api.ts:3985` |
| `setNotificationState` | **PUT** `/api/modules/notifications/{id}/state` | `Promise<NotificationMutation>` | `apps/tenant-runtime/src/api.ts:3973` |
| `setRecordActivityFavorite` | **PUT** `/api/modules/record-activity/{recordId}/favorite` | `Promise<FavoriteMutation>` | `apps/tenant-runtime/src/api.ts:3678` |
| `setRecordGraphFavorite` | **PUT** `/api/modules/record-graph/{recordId}/favorite` | `Promise<FavoriteMutation>` | `apps/tenant-runtime/src/api.ts:3561` |
| `setReservationStatus` | **PUT** `/api/modules/reservations/{recordId}/status` | `Promise<ReservationMutation>` | `apps/tenant-runtime/src/api.ts:1905` |
| `setWebLinkFavorite` | **PUT** `/api/modules/web-links/{recordId}/favorite` | `Promise<WebLinkMutation>` | `apps/tenant-runtime/src/api.ts:2917` |
| `setWorkOrderStatus` | **PUT** `/api/modules/work-orders/{recordId}/status` | `Promise<WorkOrderMutation>` | `apps/tenant-runtime/src/api.ts:1592` |
| `startChecklistRun` | **POST** `/api/modules/checklists-signoffs/runs` | `Promise<ChecklistMutation>` | `apps/tenant-runtime/src/api.ts:1706` |
| `submitChecklistForSignoff` | **POST** `/api/modules/checklists-signoffs/runs/{checklistRunId}/submit` | `Promise<ChecklistMutation>` | `apps/tenant-runtime/src/api.ts:1744` |
| `submitRuntimeForm` | **POST** `/api/runtime/forms/{pageKey}/{formName}/submissions` | `Promise<RuntimeFormSubmissionResponse>` | `apps/tenant-runtime/src/api.ts:5060` |
| `tenantFetch` | **GET** `path` | `Promise<Response>` | `apps/tenant-runtime/src/api.ts:992` |
| `tenantSessionFetch` | **GET** `input` | `Promise<Response>` | `apps/tenant-runtime/src/api.ts:949` |
| `transitionCaseFlowCase` | **POST** `/api/modules/dynamic/caseflow-cases/{recordId}/transition` | `Promise<CaseFlowTransitionResult>` | `apps/tenant-runtime/src/api.ts:4238` |
| `undoTenantPageAdoption` | **DELETE** `pageAdoptionBase(pageKey)` | `Promise<boolean>` | `apps/tenant-runtime/src/api.ts:5285` |
| `unlinkKnowledgeFromRecord` | **DELETE** `/api/modules/record-graph/knowledge-relations/{recordRelationId}` | `Promise<KnowledgeRelationMutation>` | `apps/tenant-runtime/src/api.ts:3612` |
| `updateActiveWorkplace` | **PATCH** `/api/modules/active-workplace/{activeWorkplaceId}` | `Promise<ActiveWorkplaceMutation>` | `apps/tenant-runtime/src/api.ts:3739` |
| `updateCalendarEvent` | **PUT** `/api/modules/calendar/{recordId}` | `Promise<CalendarMutation>` | `apps/tenant-runtime/src/api.ts:2141` |
| `updateChatMessage` | **PUT** `/api/modules/chat-rooms/{recordId}/messages/{chatMessageId}` | `Promise<ChatRoomMutation>` | `apps/tenant-runtime/src/api.ts:3011` |
| `updateChatRoom` | **PUT** `/api/modules/chat-rooms/{recordId}` | `Promise<ChatRoomMutation>` | `apps/tenant-runtime/src/api.ts:2976` |
| `updateChecklistItem` | **PUT** `/api/modules/checklists-signoffs/items/{checklistRunItemId}` | `Promise<ChecklistMutation>` | `apps/tenant-runtime/src/api.ts:1715` |
| `updateChecklistTemplate` | **PUT** `/api/modules/checklists-signoffs/templates/{checklistTemplateId}` | `Promise<ChecklistMutation>` | `apps/tenant-runtime/src/api.ts:1642` |
| `updateCompanyNews` | **PUT** `/api/modules/company-news/{recordId}` | `Promise<CompanyNewsMutation>` | `apps/tenant-runtime/src/api.ts:2784` |
| `updateContact` | **PUT** `/api/modules/contacts/{recordId}` | `Promise<ContactMutation>` | `apps/tenant-runtime/src/api.ts:1373` |
| `updateConversation` | **PUT** `/api/modules/conversations/{recordId}` | `Promise<ConversationMutation>` | `apps/tenant-runtime/src/api.ts:2544` |
| `updateDiscussionBoard` | **PUT** `/api/modules/discussion-boards/{recordId}` | `Promise<DiscussionMutation>` | `apps/tenant-runtime/src/api.ts:3150` |
| `updateDiscussionPost` | **PUT** `/api/modules/discussion-boards/posts/{recordId}` | `Promise<DiscussionMutation>` | `apps/tenant-runtime/src/api.ts:3240` |
| `updateDiscussionTopic` | **PUT** `/api/modules/discussion-boards/topics/{recordId}` | `Promise<DiscussionMutation>` | `apps/tenant-runtime/src/api.ts:3205` |
| `updateDynamicModuleRecord` | **PUT** `/api/modules/dynamic/{moduleKey}/{recordId}` | `Promise<DynamicModuleMutation>` | `apps/tenant-runtime/src/api.ts:4182` |
| `updateFavoritePreferences` | **PUT** `/api/modules/favorites/{recordId}/preferences` | `Promise<FavoriteMutation>` | `apps/tenant-runtime/src/api.ts:3483` |
| `updateFile` | **PUT** `/api/modules/files/{recordId}` | `Promise<FileMutation>` | `apps/tenant-runtime/src/api.ts:2265` |
| `updateKnowledgeArticle` | **PUT** `/api/modules/knowledge-articles/{recordId}` | `Promise<KnowledgeArticleMutation>` | `apps/tenant-runtime/src/api.ts:4294` |
| `updateKnowledgeCore` | **PUT** `/api/modules/knowledge-core/{recordId}` | `Promise<KnowledgeCoreMutation>` | `apps/tenant-runtime/src/api.ts:4370` |
| `updateKnowledgeCoreCollection` | **PUT** `/api/modules/knowledge-core/collections/{collectionId}` | `Promise<KnowledgeCollectionMutation>` | `apps/tenant-runtime/src/api.ts:4468` |
| `updateMailReaderMailbox` | **PUT** `/api/modules/mail-reader/mailboxes/{mailboxId}` | `inferred` | `apps/tenant-runtime/src/api.ts:3380` |
| `updateRecordType` | **PUT** `/api/runtime/record-types/{moduleKey}` | `Promise<RecordType>` | `apps/tenant-runtime/src/api.ts:1150` |
| `updateReservationCustomFields` | **PUT** `/api/modules/reservations/{recordId}/custom-fields` | `Promise<ReservationMutation>` | `apps/tenant-runtime/src/api.ts:1928` |
| `updateReservationFollowup` | **PUT** `/api/modules/reservations/{recordId}/followups` | `Promise<ReservationMutation>` | `apps/tenant-runtime/src/api.ts:1939` |
| `updateTenantInboundEndpoint` | Delegates through `mutateTenantInboundEndpoint` | `inferred` | `apps/tenant-runtime/src/api.ts:4642` |
| `updateTenantPaymentPolicy` | **PUT** `/api/modules/payments/settings/{moduleKey}` | `Promise<TenantPaymentMutation>` | `apps/tenant-runtime/src/api.ts:1958` |
| `updateWebLink` | **PUT** `/api/modules/web-links/{recordId}` | `Promise<WebLinkMutation>` | `apps/tenant-runtime/src/api.ts:2892` |
| `updateWorkOrder` | **PUT** `/api/modules/work-orders/{recordId}` | `Promise<WorkOrderMutation>` | `apps/tenant-runtime/src/api.ts:1571` |
| `uploadFile` | **POST** `/api/modules/files/upload` | `Promise<FileMutation>` | `apps/tenant-runtime/src/api.ts:2219` |
| `uploadFileVersion` | **POST** `/api/modules/files/{recordId}/versions` | `Promise<FileMutation>` | `apps/tenant-runtime/src/api.ts:2388` |
| `uploadTenantAsset` | **POST** `/api/assets` | `Promise<TenantAssetMutation>` | `apps/tenant-runtime/src/api.ts:5339` |
| `upsertTenantPaymentConnector` | **PUT** `/api/modules/payments/connectors` | `Promise<TenantPaymentMutation>` | `apps/tenant-runtime/src/api.ts:1968` |
| `verifyTenantMfa` | Delegates through `isTenantRefreshSuccess, tenantAuthenticationRequest` | `Promise<TenantLoginSuccess>` | `apps/tenant-runtime/src/api.ts:4880` |

****In-SaaS Design authoring API** 33 exported functions**

Source: `apps/tenant-runtime/src/designApi.ts`

| Function | Transport/delegation | Return | Source |
| --- | --- | --- | --- |
| `appendDeveloperDebugEvent` | **POST** `/api/runtime/design/debug/sessions/{debugSessionId}/events` | `Promise<void>` | `apps/tenant-runtime/src/designApi.ts:388` |
| `closeDeveloperDebugSession` | **DELETE** `/api/runtime/design/debug/sessions/{debugSessionId}` | `Promise<void>` | `apps/tenant-runtime/src/designApi.ts:409` |
| `createDesignCustomField` | **POST** `designFieldsPath(moduleKey)` | `Promise<void>` | `apps/tenant-runtime/src/designApi.ts:517` |
| `createDesignPage` | **POST** `/api/runtime/design/pages` | `Promise<{ readonly pageKey: string; readonly pageVersion: number; readonly duplicatedFromPageKey?: string | null }>` | `apps/tenant-runtime/src/designApi.ts:473` |
| `loadDesignAiInsightStarters` | **GET** `/api/runtime/design/ai-insights/starters` | `Promise<DesignAiInsightStarters>` | `apps/tenant-runtime/src/designApi.ts:670` |
| `loadDesignAuthoringMap` | **GET** `/api/runtime/design/authoring` | `Promise<DesignAuthoringMap>` | `apps/tenant-runtime/src/designApi.ts:446` |
| `loadDesignAuthorization` | Delegates through `tenantSessionFetch` | `Promise<boolean>` | `apps/tenant-runtime/src/designApi.ts:186` |
| `loadDesignCustomFieldPolicy` | **GET** `` `${designFieldsPath(moduleKey)}/policy` `` | `Promise<CustomFieldPolicy>` | `apps/tenant-runtime/src/designApi.ts:527` |
| `loadDesignCustomFields` | **GET** `designFieldsPath(moduleKey)` | `Promise<CustomFieldList>` | `apps/tenant-runtime/src/designApi.ts:514` |
| `loadDesignLinkTypes` | **GET** `/api/runtime/design/link-types` | `Promise<DesignLinkTypes>` | `apps/tenant-runtime/src/designApi.ts:634` |
| `loadDesignPageDraft` | **GET** `/api/runtime/design/pages/{pageKey}` | `Promise<DesignPageDraft>` | `apps/tenant-runtime/src/designApi.ts:481` |
| `loadDesignPageHistory` | **GET** `/api/runtime/design/pages/{pageKey}/history?limit=25` | `Promise<readonly DesignPageHistoryItem[]>` | `apps/tenant-runtime/src/designApi.ts:506` |
| `loadDesignPersonalFileLimit` | **GET** `/api/runtime/design/files/personal-limit` | `Promise<DesignPersonalFileLimit>` | `apps/tenant-runtime/src/designApi.ts:536` |
| `loadDesignTenantPresentationPolicies` | **GET** `/api/runtime/design/authoring/tenant-policies` | `Promise<DesignTenantPresentationPolicyMap>` | `apps/tenant-runtime/src/designApi.ts:449` |
| `loadDeveloperDebugHistory` | **GET** ``/api/runtime/design/debug/sessions/history${afterSessionId ? `?afterSessionId={afterSessionId}` : ""}`` | `Promise<DeveloperDebugHistory>` | `apps/tenant-runtime/src/designApi.ts:425` |
| `loadDeveloperDebugHistoryTimeline` | **GET** `/api/runtime/design/debug/sessions/history/{sessionId}?afterSequence={afterSequence}` | `Promise<DeveloperDebugTimeline>` | `apps/tenant-runtime/src/designApi.ts:442` |
| `loadDeveloperDebugTimeline` | **GET** `/api/runtime/design/debug/sessions/{debugSessionId}?afterSequence={afterSequence}&top=100` | `Promise<DeveloperDebugTimeline>` | `apps/tenant-runtime/src/designApi.ts:399` |
| `parseDesignLinkType` | Delegates through `flagOf, objectOf, optionalTextOf, textOf` | `DesignLinkType` | `apps/tenant-runtime/src/designApi.ts:598` |
| `parseDesignLinkTypes` | Delegates through `objectOf, optionalTextOf, textOf` | `DesignLinkTypes` | `apps/tenant-runtime/src/designApi.ts:617` |
| `projectDeveloperDebugEvent` | Delegates through `Boolean, debugGuid, debugInteger, debugOptionalGuid, debugOptionalText, debugResponseError, debugSafeText, debugUtc, isObjectRecord` | `DeveloperDebugEvent` | `apps/tenant-runtime/src/designApi.ts:292` |
| `publishDesignPage` | **POST** `/api/runtime/design/pages/{pageKey}/publish` | `Promise<{ readonly published: boolean; readonly publishedVersion: number }>` | `apps/tenant-runtime/src/designApi.ts:497` |
| `saveDesignAiInsightStarter` | **UNKNOWN** ``directiveId ? `${designStartersPath}/${encodeURIComponent(directiveId)}` : designStartersPath`` | `Promise<DesignAiInsightStarters>` | `apps/tenant-runtime/src/designApi.ts:672` |
| `saveDesignCustomFieldPolicy` | **PUT** `` `${designFieldsPath(moduleKey)}/policy` `` | `Promise<CustomFieldPolicy>` | `apps/tenant-runtime/src/designApi.ts:530` |
| `saveDesignFeatureName` | **PUT** `/api/runtime/design/vocabulary/{moduleKey}` | `Promise<{ readonly moduleKey: string; readonly singularLabel: string | null; readonly pluralLabel: string | null }>` | `apps/tenant-runtime/src/designApi.ts:655` |
| `saveDesignLinkType` | **PUT** `/api/runtime/design/link-types/{relationKey}` | `Promise<DesignLinkType>` | `apps/tenant-runtime/src/designApi.ts:637` |
| `saveDesignMenu` | **PUT** `/api/runtime/design/authoring/user-types/{userTypeKey}/menu` | `Promise<{ readonly menuVersion: number; readonly userTypeVersion: number }>` | `apps/tenant-runtime/src/designApi.ts:464` |
| `saveDesignPageDraft` | **PUT** `/api/runtime/design/pages/{pageKey}/draft` | `Promise<DesignDraftSaveResult>` | `apps/tenant-runtime/src/designApi.ts:484` |
| `saveDesignPersonalFileLimit` | **PUT** `/api/runtime/design/files/personal-limit` | `Promise<DesignPersonalFileLimit>` | `apps/tenant-runtime/src/designApi.ts:538` |
| `saveDesignTenantPresentationPolicy` | **PUT** `/api/runtime/design/authoring/user-types/{userTypeKey}/tenant-policy` | `Promise<{readonly policyVersion:number}>` | `apps/tenant-runtime/src/designApi.ts:452` |
| `saveDesignUserType` | **PUT** `/api/runtime/design/authoring/user-types/{userTypeKey}` | `Promise<{ readonly version: number }>` | `apps/tenant-runtime/src/designApi.ts:455` |
| `startDeveloperDebugSession` | **POST** `/api/runtime/design/debug/sessions` | `Promise<DeveloperDebugSession>` | `apps/tenant-runtime/src/designApi.ts:375` |
| `updateDesignCustomField` | **PUT** `` `${designFieldsPath(moduleKey)}/${encodeURIComponent(fieldDefinitionId)}` `` | `Promise<void>` | `apps/tenant-runtime/src/designApi.ts:522` |
| `validateDesignPage` | **POST** `/api/runtime/design/pages/{pageKey}/validate` | `Promise<DesignPageValidation>` | `apps/tenant-runtime/src/designApi.ts:494` |

****createUniversalInboxHttpClient** 17 public methods**

Default same-origin base: `/api/inbox/items`

| Method | Compiler-extracted call | Source |
| --- | --- | --- |
| `list` | ``request(`${basePath}?${filterQuery(filter)}`, signal)`` | `modules/universal-inbox/src/client.ts:182` |
| `get` | ``request(`${basePath}/${encodeURIComponent(normalizedId)}`, signal)`` | `modules/universal-inbox/src/client.ts:187` |
| `badge` | ``request(`${basePath.replace(/\/items$/, "")}/badge`, signal)`` | `modules/universal-inbox/src/client.ts:202` |
| `badgeIndicator` | ``request(`${basePath.replace(/\/items$/, "")}/badge/indicator`, signal)`` | `modules/universal-inbox/src/client.ts:207` |
| `notifications` | ``request(`${notificationsPath}/notifications?top=${topN}`, signal)`` | `modules/universal-inbox/src/client.ts:212` |
| `deliveryDebug` | ``request(`${root}/delivery/debug?${query}`, signal)`` | `modules/universal-inbox/src/client.ts:224` |
| `retryDelivery` | ``fetchImplementation(`${root}/delivery/${encodeURIComponent(outboundMessageId.toLowerCase())}/retry`, { method: "POST", credentials: "same-origin", headers, signal })`` | `modules/universal-inbox/src/client.ts:232` |
| `setReadState` | `mutate(inboxItemId, { isUnread, expectedActivityVersion }, signal)` | `modules/universal-inbox/src/client.ts:250` |
| `setStatus` | `mutate(inboxItemId, {           status,           expectedActivityVersion,           ...(snoozedUntilUtc ? { snoozedUntilUtc } : {}),         }, signal)` | `modules/universal-inbox/src/client.ts:258` |
| `setPriority` | `mutate(inboxItemId, { priority, expectedActivityVersion }, signal)` | `modules/universal-inbox/src/client.ts:280` |
| `setAssignment` | `mutate(inboxItemId, { assignmentMode, expectedActivityVersion }, signal)` | `modules/universal-inbox/src/client.ts:292` |
| `reply` | ``fetchImplementation(`${basePath}/${encodeURIComponent(inboxItemId.toLowerCase())}/reply`, {           method: "POST",           credentials: "same-origin",           headers,           body: JSON.stringify(reply),           signal,         })`` | `modules/universal-inbox/src/client.ts:311` |
| `getChannelTicketingSettings` | ``request(`${root}/channels/ticketing`, signal)`` | `modules/universal-inbox/src/client.ts:348` |
| `setChannelTicketing` | ``fetchImplementation(`${root}/channels/${encodeURIComponent(channelConnectionId.toLowerCase())}/ticketing`, {         method: "PUT", credentials: "same-origin", headers,         body: JSON.stringify({ isTicketingEnabled, ticketPrefix: normalizedPrefix }), signal,       })`` | `modules/universal-inbox/src/client.ts:352` |
| `getEmailTicketingSettings` | ``request(`${root}/email-channels/ticketing`, signal)`` | `modules/universal-inbox/src/client.ts:369` |
| `setEmailTicketing` | ``fetchImplementation(`${root}/email-channels/${encodeURIComponent(channelConnectionId.toLowerCase())}/ticketing`, {           method: "PUT",           credentials: "same-origin",           headers,           body: JSON.stringify({             isTicketingEnabled,             ticketPrefix: normalizedPrefix,           }),           signal,         })`` | `modules/universal-inbox/src/client.ts:377` |
| `decideWorkflowApproval` | ``fetchImplementation(`${basePath}/${encodeURIComponent(inboxItemId.toLowerCase())}/workflow-approval`, {           method: "POST",           credentials: "same-origin",           headers,           body: JSON.stringify({             expectedActivityVersion,             decision,             ...(normalizedReason ? { reason: normalizedReason } : {}),           }),           signal,         })`` | `modules/universal-inbox/src/client.ts:419` |

****createApprovalQueueHttpClient** 5 public methods**

Default same-origin base: `/api/goclaw/approvals`

| Method | Compiler-extracted call | Source |
| --- | --- | --- |
| `list` | `fetchImplementation(basePath + "?top=" + encodeURIComponent(String(topN)), {           method: "GET",           credentials: "same-origin",           headers: headers(),           signal,         })` | `modules/universal-inbox/src/approvalClient.ts:94` |
| `approve` | `fetchImplementation(batchPath(suggestionBatchId, "approve"), {         method: "POST",         credentials: "same-origin",         headers: headers(true),         body: JSON.stringify(input),         signal,       })` | `modules/universal-inbox/src/approvalClient.ts:110` |
| `reject` | `disposition(suggestionBatchId, "reject", reviewNotes, signal)` | `modules/universal-inbox/src/approvalClient.ts:125` |
| `takeOver` | `disposition(suggestionBatchId, "take-over", reviewNotes, signal)` | `modules/universal-inbox/src/approvalClient.ts:128` |
| `retry` | `disposition(suggestionBatchId, "retry", reviewNotes, signal)` | `modules/universal-inbox/src/approvalClient.ts:131` |

### Non-page tenant and Design server routes

These are the additional server routes outside the 163 page-module operations. A declared-interface row proves the controller-to-procedure chain. An unresolved row remains useful route/controller evidence but is not presented as a one-procedure contract; orchestration and factory services can legitimately span multiple operations.

| Host | Route | Browser | Service | Procedure/evidence |
| --- | --- | --- | --- | --- |
| tenant-runtime | **GET**
`/api/account-admin/diagnostics/sessions` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/account-admin/diagnostics/sessions/{debugSessionId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/account-admin/snowflake` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/account-admin/snowflake` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/account-admin/snowflake/test` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/account-admin/snowflake/export` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/account-admin/snowflake/enabled` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/account-admin/snowflake/schedule` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/ai/datachat/ask` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/ai/datachat/glossary/confirm` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/assets` | `No direct browser join` | `ITenantAssetsService.ListAsync` | `sp_SaasAppAssets_ListSecured`
declared-interface |
| tenant-runtime | **POST**
`/api/assets` | `uploadTenantAsset` | `ITenantAssetsService.UploadAsync` | `sp_SaasAppAssets_CreateSecured, sp_SaasAppAssets_QueueUnreferencedCleanupSecured`
declared-interface |
| tenant-runtime | **GET**
`/api/assets/{assetId:guid}/content` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **DELETE**
`/api/assets/{assetId:guid}` | `deleteTenantAsset` | `ITenantAssetsService.DeleteAsync` | `sp_SaasAppAssets_DeleteSecured`
declared-interface |
| tenant-runtime | **PUT**
`/api/goclaw/agents/{goClawAgentId:guid}/authority` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/goclaw/skills` | `No direct browser join` | `ITenantGoClawSkillsService.ListAsync` | `sp_Tenant_AuthorizeMcpSkillAuthoring, sp_Tenant_EnsurePersonalGoClawAgent, sp_Tenant_ListManageableGoClawSkillAgents`
declared-interface |
| tenant-runtime | **POST**
`/api/goclaw/skills` | `No direct browser join` | `ITenantGoClawSkillsService.CreateAsync` | `sp_Tenant_AuthorizeMcpSkillAuthoring, sp_Tenant_EnsurePersonalGoClawAgent`
declared-interface |
| tenant-runtime | **POST**
`/api/goclaw/skills/{skillVersionId:guid}/revoke` | `No direct browser join` | `ITenantGoClawSkillsService.RevokeAsync` | `sp_Tenant_AuthorizeMcpSkillAuthoring, sp_Tenant_EnsurePersonalGoClawAgent`
declared-interface |
| tenant-runtime | **PUT**
`/api/goclaw/skills/assignments` | `No direct browser join` | `ITenantGoClawSkillsService.AssignAsync` | `sp_Developer_AuthorizeGoClawSkillManagement`
declared-interface |
| tenant-runtime | **GET**
`/api/goclaw/team` | `No direct browser join` | `ITenantGoClawTeamService.ListAsync` | `sp_GoClaw_GetTeamJson`
declared-interface |
| tenant-runtime | **POST**
`/api/goclaw/team` | `No direct browser join` | `ITenantGoClawTeamService.CreateAsync` | `sp_GoClaw_CreateTeamAgent`
declared-interface |
| tenant-runtime | **PUT**
`/api/goclaw/team/{goClawUserId:guid}` | `No direct browser join` | `ITenantGoClawTeamService.UpdateAsync` | `sp_GoClaw_UpdateTeamAgent`
declared-interface |
| tenant-runtime | **PUT**
`/api/goclaw/team/{goClawUserId:guid}/security` | `No direct browser join` | `ITenantGoClawTeamService.SetSecurityAsync` | `sp_GoClaw_SetTeamSecurity, sp_GoClaw_GetTeamJson`
delegated-interface |
| tenant-runtime | **DELETE**
`/api/goclaw/team/{goClawUserId:guid}` | `No direct browser join` | `ITenantGoClawTeamService.DeactivateAsync` | `sp_GoClaw_UpdateTeamAgent`
delegated-interface |
| tenant-runtime | **POST**
`/api/inbox/items/{inboxItemId:guid}/workflow-approval` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/modules/record-activity/{recordId:guid}/history` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/outsideformsubmissions/server/{endpointId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **OPTIONS**
`/api/outsideformsubmissions/browser/{endpointId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/outsideformsubmissions/browser/{endpointId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/outsideformsubmissions/endpoints` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/outsideformsubmissions/browser-challenge` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/outsideformsubmissions/endpoints` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/outsideformsubmissions/endpoints/{endpointId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/outsideformsubmissions/{submissionId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/bootstrap/{pageKey}` | `loadRuntimeBootstrap` | `ITenantBootstrapService.LoadAsync` | `sp_Tenant_ResolveHostIdentity, sp_Runtime_GetPageBootstrap, sp_Runtime_ApplyTenantNavigationOverride`
declared-interface |
| tenant-runtime | **GET**
`/api/runtime/data/{bindingKey}` | `No direct browser join` | `ITenantDataBindingService.ResolveAsync` | `sp_ResolveDataBindingByKey, buildwithHQ_CustomerCopy::dbo.`
declared-interface |
| tenant-runtime | **POST**
`/api/runtime/data/batch` | `loadRuntimeDataBindings` | `ITenantDataBindingService.ResolveBatchAsync` | `sp_ResolveDataBindingByKey, buildwithHQ_CustomerCopy::dbo.`
declared-interface |
| tenant-runtime | **GET**
`/api/runtime/derived-legos/{moduleKey}/catalog` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/derived-legos/{moduleKey}/presentation` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/design/ai-insights/starters` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/runtime/design/ai-insights/starters` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/runtime/design/ai-insights/starters/{directiveId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/design/authoring` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/runtime/design/authoring/user-types/{userTypeKey}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/runtime/design/authoring/user-types/{userTypeKey}/menu` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/runtime/design/authoring/user-types/{userTypeKey}/tenant-policy` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/design/authoring/tenant-policies` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/design/authorization` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/runtime/design/debug/sessions` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/runtime/design/debug/sessions/{debugSessionId:guid}/events` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/design/debug/sessions/{debugSessionId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/design/debug/sessions/history` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/design/debug/sessions/history/{debugSessionId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **DELETE**
`/api/runtime/design/debug/sessions/{debugSessionId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/design/fields/{moduleKey}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/runtime/design/fields/{moduleKey}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/runtime/design/fields/{moduleKey}/{fieldDefinitionId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/design/fields/{moduleKey}/policy` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/runtime/design/fields/{moduleKey}/policy` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/design/files/personal-limit` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/runtime/design/files/personal-limit` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/design/link-types` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/runtime/design/link-types/{relationKey}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/design/pages` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/runtime/design/pages` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/design/pages/{pageKey}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/runtime/design/pages/{pageKey}/draft` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/runtime/design/pages/{pageKey}/validate` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/runtime/design/pages/{pageKey}/publish` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/design/pages/{pageKey}/history` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/runtime/design/vocabulary/{moduleKey}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/runtime/diagnostics/browser-failures` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/feature-readiness` | `getTenantFeatureReadiness` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/forms/destinations` | `No direct browser join` | `ITenantFormsService.ListDestinationsAsync` | `sp_FormInboundRoute_ListSecured`
declared-interface |
| tenant-runtime | **PUT**
`/api/runtime/forms/destinations/{pageKey}/{formName}` | `No direct browser join` | `ITenantFormsService.SaveDestinationAsync` | `sp_FormInboundRoute_SaveSecured`
declared-interface |
| tenant-runtime | **POST**
`/api/runtime/forms/{pageKey}/{formName}/submissions` | `submitRuntimeForm` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/runtime/lego/actions` | `executeRuntimeLegoAction` | `ITenantLegoActionBroker.ExecuteAsync` | `sp_Tenant_ResolveHostIdentity, sp_Runtime_GetPageBootstrap, sp_Runtime_ApplyTenantNavigationOverride`
delegated-interface |
| tenant-runtime | **GET**
`/api/runtime/pages/{pageKey}/adoption` | `No direct browser join` | `ITenantPageRevisionsService.GetDriftAsync` | `sp_AssertTenantPageOwner, sp_GetPageDrift`
declared-interface |
| tenant-runtime | **POST**
`/api/runtime/pages/{pageKey}/adoption` | `No direct browser join` | `ITenantPageRevisionsService.AdoptAsync` | `sp_ValidatePageJson, sp_ApplyTenantPageAdoption, sp_AssertTenantPageOwner, sp_AcquirePageEditLock, sp_GetPageDrift`
delegated-interface |
| tenant-runtime | **DELETE**
`/api/runtime/pages/{pageKey}/adoption` | `No direct browser join` | `ITenantPageRevisionsService.UndoAdoptionAsync` | `sp_UndoTenantPageAdoption, sp_AssertTenantPageOwner, sp_AcquirePageEditLock`
delegated-interface |
| tenant-runtime | **GET**
`/api/runtime/pages/drift` | `listTenantPageDrift` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/runtime/pages/{pageKey}/edit-lock` | `acquirePageEditLock` | `ITenantPageRevisionsService.AcquireEditLockAsync` | `sp_AssertTenantPageOwner, sp_AcquirePageEditLock`
declared-interface |
| tenant-runtime | **DELETE**
`/api/runtime/pages/{pageKey}/edit-lock` | `releasePageEditLock` | `ITenantPageRevisionsService.ReleaseEditLockAsync` | `sp_AssertTenantPageOwner, sp_ReleasePageEditLock`
declared-interface |
| tenant-runtime | **GET**
`/api/runtime/fields/{moduleKey}` | `No direct browser join` | `ITenantCustomFieldsService.ListVisibleAsync` | `sp_Tenant_FieldDefinition_ListVisibleSecured`
declared-interface |
| tenant-runtime | **GET**
`/api/runtime/pages/{pageKey}/fields/{moduleKey}` | `No direct browser join` | `ITenantCustomFieldsService.ListAsync` | `sp_Tenant_FieldDefinition_ListSecured`
declared-interface |
| tenant-runtime | **POST**
`/api/runtime/pages/{pageKey}/fields/{moduleKey}` | `No direct browser join` | `ITenantCustomFieldsService.CreateAsync` | `sp_Tenant_FieldDefinition_CreateSecured`
declared-interface |
| tenant-runtime | **PUT**
`/api/runtime/pages/{pageKey}/fields/{moduleKey}/{fieldDefinitionId:guid}` | `No direct browser join` | `ITenantCustomFieldsService.UpdateAsync` | `sp_Tenant_FieldDefinition_UpdateSecured`
declared-interface |
| tenant-runtime | **GET**
`/api/runtime/pages/{pageKey}/revisions` | `No direct browser join` | `ITenantPageRevisionsService.ListAsync` | `sp_AssertTenantPageOwner, sp_GetPageHistory`
declared-interface |
| tenant-runtime | **GET**
`/api/runtime/pages/{pageKey}/revisions/{pageHistoryId:guid}` | `No direct browser join` | `ITenantPageRevisionsService.GetAsync` | `sp_AssertTenantPageOwner, sp_GetPageHistory, sp_GetPageHistoryJson`
declared-interface |
| tenant-runtime | **POST**
`/api/runtime/pages/{pageKey}/revisions/save` | `No direct browser join` | `ITenantPageRevisionsService.SaveAsync` | `sp_SaveTenantPageOverrideRaw`
declared-interface |
| tenant-runtime | **POST**
`/api/runtime/pages/{pageKey}/revisions/{pageHistoryId:guid}/restore` | `No direct browser join` | `ITenantPageRevisionsService.RestoreAsync` | `sp_ValidatePageJson, sp_RestorePageVersion, sp_AssertTenantPageOwner, sp_GetPageHistory, sp_GetPageHistoryJson`
delegated-interface |
| tenant-runtime | **GET**
`/api/runtime/record-deletions` | `No direct browser join` | `ITenantRecordDeletionService.ListHistoryAsync` | `sp_RecordUserDeletion_ListHistorySecured`
declared-interface |
| tenant-runtime | **POST**
`/api/runtime/record-deletions/{recordId:guid}/restore` | `No direct browser join` | `ITenantRecordDeletionService.RestoreAsync` | `sp_RecordRestoreSecured`
declared-interface |
| tenant-runtime | **POST**
`/api/runtime/record-deletions/{recordId:guid}/permanent` | `No direct browser join` | `ITenantRecordDeletionService.MakePermanentAsync` | `sp_RecordDeletion_MakePermanentSecured`
declared-interface |
| tenant-runtime | **GET**
`/api/runtime/record-scope/create-roles` | `getRecordCreateScopeChoices` | `ITenantRecordScopeService.ListCreateRolesAsync` | `sp_RecordScope_ListCreateRolesSecured`
declared-interface |
| tenant-runtime | **GET**
`/api/runtime/record-scope/records/{recordId:guid}/pages` | `getNativeRecordPages` | `ITenantRecordScopeService.GetNativePagesAsync` | `sp_RecordScope_GetNativePagesSecured`
declared-interface |
| tenant-runtime | **GET**
`/api/runtime/record-scope/records/{recordId:guid}` | `getRecordCurrentScope` | `ITenantRecordScopeService.GetCurrentScopeAsync` | `sp_RecordScope_GetCurrentSecured`
declared-interface |
| tenant-runtime | **POST**
`/api/runtime/record-scope/records/{recordId:guid}/scope` | `No direct browser join` | `ITenantRecordScopeService.MoveScopeAsync` | `sp_RecordScope_MoveSecured`
declared-interface |
| tenant-runtime | **GET**
`/api/runtime/route` | `loadRuntimeBootstrapBySlug` | `ITenantPageRouteService.LoadBySlugAsync` | `sp_ResolvePageBySlug, sp_Tenant_ResolveHostIdentity, sp_Runtime_GetPageBootstrap, sp_Runtime_ApplyTenantNavigationOverride`
delegated-interface |
| tenant-runtime | **GET**
`/api/runtime/secure-fields/records/{recordId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/runtime/secure-fields/records/{recordId:guid}/{fieldId:guid}/reveal` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/runtime/secure-fields/records/{recordId:guid}/{fieldId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/secure-fields/definitions/{fieldId:guid}/policy` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/runtime/secure-fields/definitions/{fieldId:guid}/policy` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/runtime/vocabulary` | `loadAppVocabulary` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/webhooks/twilio/sms` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/workflow-designer/capabilities` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/workflow-designer/definitions` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/api/workflow-designer/definitions/{workflowDefinitionId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/workflow-designer/definitions` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **PUT**
`/api/workflow-designer/definitions/{workflowDefinitionId:guid}` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/workflow-designer/definitions/{workflowDefinitionId:guid}/clone` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/workflow-designer/definitions/{workflowDefinitionId:guid}/publish` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **POST**
`/api/workflow-designer/definitions/validate` | `No direct browser join` | `Factory/controller orchestration` | `Orchestration/unresolved to one procedure`
unresolved |
| tenant-runtime | **GET**
`/{saasAppId:guid}/{assetId:guid}` | `No direct browser join` | `IPublicTenantAssetsService.DownloadAsync` | `sp_Assets_ResolveSaasAppIdentity, sp_SaasAppAssets_GetPublicContent`
declared-interface |

## Complete React catalog source

The searchable component is generated from the same JSON used above. Import the CSS only for the styled export.

**BuildWithHQComponentCatalog.tsx**

```

import { useMemo, useState } from "react";
import { buildWithHQCatalog, type CatalogModule } from "./catalog-data.generated";

export interface BuildWithHQComponentCatalogProps {
  readonly initialModuleKey?: string;
  readonly styled?: boolean;
}

const procedureNames = (module: CatalogModule): readonly string[] =>
  [...new Set(module.operations.flatMap((operation) =>
    operation.procedures.map((procedure) => procedure.procedure ?? procedure.key),
  ))];

const CatalogBody = ({ initialModuleKey, styled = false }: BuildWithHQComponentCatalogProps) => {
  const [query, setQuery] = useState("");
  const initial = buildWithHQCatalog.modules.find((module) =>
    module.module_key === initialModuleKey || module.component_key === initialModuleKey,
  ) ?? buildWithHQCatalog.modules[0];
  const [selectedKey, setSelectedKey] = useState(initial?.api_base_path ?? "");
  const filtered = useMemo(() => {
    const needle = query.trim().toLocaleLowerCase("en-US");
    if (!needle) return buildWithHQCatalog.modules;
    return buildWithHQCatalog.modules.filter((module) => [
      module.display_name,
      module.module_key,
      module.component_key,
      module.api_base_path,
      ...module.operations.map((operation) => operation.route),
      ...procedureNames(module),
    ].some((value) => value?.toLocaleLowerCase("en-US").includes(needle)));
  }, [query]);
  const selected = filtered.find((module) => module.api_base_path === selectedKey)
    ?? filtered[0]
    ?? buildWithHQCatalog.modules[0];

  return (
    <section className={styled ? "bwhq-catalog bwhq-catalog--styled" : undefined}>
      <header className={styled ? "bwhq-catalog__header" : undefined}>
        <div>
          <p>Generated component and contract evidence</p>
          <h1>BuildWithHQ component catalog</h1>
          <p>{buildWithHQCatalog.totals.modules} SDK surfaces, {buildWithHQCatalog.totals.components_bound} page renderers and {buildWithHQCatalog.totals.operations} server operations.</p>
        </div>
        <label>
          Search components, routes or procedures
          <input value={query} onChange={(event) => setQuery(event.target.value)} type="search" />
        </label>
      </header>

      <div className={styled ? "bwhq-catalog__layout" : undefined}>
        <nav aria-label="First-class modules" className={styled ? "bwhq-catalog__menu" : undefined}>
          <h2>Modules and API surfaces</h2>
          <ul>
            {filtered.map((module) => (
              <li key={module.api_base_path}>
                <button type="button" aria-current={selected === module ? "page" : undefined} onClick={() => setSelectedKey(module.api_base_path)}>
                  <span>{module.display_name}</span>
                  <small>{module.operations.length} operations</small>
                </button>
              </li>
            ))}
          </ul>
        </nav>

        <main className={styled ? "bwhq-catalog__main" : undefined}>
          {selected ? (
            <article>
              <header>
                <p>{selected.component_key ?? "Server API surface"}</p>
                <h2>{selected.display_name}</h2>
                <code>{selected.api_base_path}</code>
              </header>
              <dl className={styled ? "bwhq-catalog__facts" : undefined}>
                <div><dt>React renderer</dt><dd>{selected.component.name ?? "Not a page renderer"}</dd></div>
                <div><dt>SDK descriptor</dt><dd>{selected.descriptor.file}:{selected.descriptor.line}</dd></div>
                <div><dt>Runtime proof</dt><dd>{selected.operations.filter((operation) => operation.runtime_evidence.status === "observed").length}/{selected.operations.length} observed in supplied evidence</dd></div>
              </dl>
              <div className={styled ? "bwhq-catalog__table" : undefined}>
                <table>
                  <thead><tr><th>HTTP</th><th>Browser function</th><th>Service member</th><th>Stored procedure</th><th>Evidence</th></tr></thead>
                  <tbody>
                    {selected.operations.map((operation) => (
                      <tr key={operation.operation_id}>
                        <td><strong>{operation.method}</strong><br /><code>{operation.route}</code></td>
                        <td>{operation.browser_calls.length ? operation.browser_calls.map((call) => <code key={call.function}>{call.function}<br /></code>) : <span>Server API only</span>}</td>
                        <td><code>{operation.service.interface}.{operation.service.method}</code></td>
                        <td>{operation.procedures.map((procedure) => <code key={procedure.key}>{procedure.procedure ?? procedure.key}<br /></code>)}</td>
                        <td>{operation.join_evidence}<br /><small>{operation.runtime_evidence.status}</small></td>
                      </tr>
                    ))}
                  </tbody>
                </table>
              </div>
            </article>
          ) : <p>No catalog entry matches that search.</p>}
        </main>

        <aside className={styled ? "bwhq-catalog__aside" : undefined}>
          <h2>Authoring contracts</h2>
          <h3>Core blocks</h3>
          <ul>{buildWithHQCatalog.core_components.map((component) => <li key={component.component_key}><code>{component.component_key}</code></li>)}</ul>
          <h3>Safe data flow</h3>
          <ol>
            <li>Load the server-produced page bootstrap.</li>
            <li>Render only returned component contracts.</li>
            <li>Call the authenticated API or a reviewed binding key.</li>
            <li>Let SQL apply tenant, DataRole, record and location scope.</li>
          </ol>
          <p><strong>Never send a database name or tenant identifier as proof of access.</strong></p>
        </aside>
      </div>
    </section>
  );
};

export const UnstyledBuildWithHQComponentCatalog = (props: Omit<BuildWithHQComponentCatalogProps, "styled">) =>
  <CatalogBody {...props} styled={false} />;

export const StyledBuildWithHQComponentCatalog = (props: Omit<BuildWithHQComponentCatalogProps, "styled">) =>
  <CatalogBody {...props} styled />;
```

**buildwithhq-component-catalog.css**

```

.bwhq-catalog--styled {
  --catalog-border: #dce2ea;
  --catalog-ink: #172033;
  --catalog-muted: #637087;
  --catalog-accent: #3659e3;
  color: var(--catalog-ink);
  font: 14px/1.5 Inter, ui-sans-serif, system-ui, sans-serif;
  width: 100%;
}
.bwhq-catalog--styled * { box-sizing: border-box; }
.bwhq-catalog__header { align-items: end; border-bottom: 1px solid var(--catalog-border); display: flex; gap: 32px; justify-content: space-between; padding: 24px; }
.bwhq-catalog__header h1 { font-size: clamp(1.8rem, 4vw, 3rem); margin: 0; }
.bwhq-catalog__header p { color: var(--catalog-muted); margin: 4px 0; }
.bwhq-catalog__header label { display: grid; font-weight: 700; gap: 6px; min-width: min(360px, 100%); }
.bwhq-catalog__header input { border: 1px solid var(--catalog-border); border-radius: 8px; font: inherit; padding: 10px 12px; }
.bwhq-catalog__layout { display: grid; grid-template-columns: minmax(220px, 280px) minmax(0, 1fr) minmax(220px, 280px); min-height: 680px; width: 100%; }
.bwhq-catalog__menu, .bwhq-catalog__aside { padding: 20px; }
.bwhq-catalog__menu { border-right: 1px solid var(--catalog-border); }
.bwhq-catalog__aside { border-left: 1px solid var(--catalog-border); }
.bwhq-catalog__menu h2, .bwhq-catalog__aside h2 { font-size: 1rem; margin-top: 0; }
.bwhq-catalog__menu ul, .bwhq-catalog__aside ul { list-style: none; margin: 0; padding: 0; }
.bwhq-catalog__menu button { background: transparent; border: 0; border-radius: 7px; color: inherit; cursor: pointer; display: grid; font: inherit; padding: 9px 10px; text-align: left; width: 100%; }
.bwhq-catalog__menu button[aria-current="page"] { background: #eef2ff; color: #243da2; }
.bwhq-catalog__menu small { color: var(--catalog-muted); }
.bwhq-catalog__main { min-width: 0; padding: 28px; }
.bwhq-catalog__main article > header p { color: var(--catalog-accent); font-weight: 700; margin: 0; }
.bwhq-catalog__main article > header h2 { font-size: 2rem; margin: 2px 0 8px; }
.bwhq-catalog__facts { display: grid; gap: 10px; grid-template-columns: repeat(3, minmax(0, 1fr)); margin: 24px 0; }
.bwhq-catalog__facts div { background: #f7f9fc; border-radius: 8px; padding: 12px; }
.bwhq-catalog__facts dt { color: var(--catalog-muted); font-size: .75rem; font-weight: 700; text-transform: uppercase; }
.bwhq-catalog__facts dd { margin: 4px 0 0; overflow-wrap: anywhere; }
.bwhq-catalog__table { overflow-x: auto; }
.bwhq-catalog__table table { border-collapse: collapse; min-width: 900px; width: 100%; }
.bwhq-catalog__table th, .bwhq-catalog__table td { border-bottom: 1px solid var(--catalog-border); padding: 10px; text-align: left; vertical-align: top; }
.bwhq-catalog__table code { font: 12px/1.45 "JetBrains Mono", ui-monospace, monospace; overflow-wrap: anywhere; }
.bwhq-catalog__aside li { margin: 5px 0; }
@media (max-width: 1050px) { .bwhq-catalog__layout { grid-template-columns: 240px minmax(0, 1fr); } .bwhq-catalog__aside { border-left: 0; border-top: 1px solid var(--catalog-border); grid-column: 1 / -1; } }
@media (max-width: 720px) { .bwhq-catalog__header { align-items: stretch; flex-direction: column; } .bwhq-catalog__layout { display: block; } .bwhq-catalog__menu { border-bottom: 1px solid var(--catalog-border); border-right: 0; } .bwhq-catalog__facts { grid-template-columns: 1fr; } }
.bwhq-capability { border: 1px solid var(--catalog-border, #dce2ea); border-radius: 12px; color: var(--catalog-ink, #172033); display: grid; gap: 12px; padding: 20px; }
.bwhq-capability header p, .bwhq-capability header h2 { margin: 0; }
.bwhq-capability header p { color: var(--catalog-accent, #3659e3); font-weight: 700; }
.bwhq-capability header span { background: #eef2ff; border-radius: 999px; display: inline-block; margin-top: 8px; padding: 3px 9px; }
.bwhq-capability h3, .bwhq-capability p, .bwhq-capability ul, .bwhq-capability dl { margin: 0; }
.bwhq-capability dl { display: grid; gap: 8px; grid-template-columns: repeat(3, minmax(0, 1fr)); }
.bwhq-capability dl div { background: #f7f9fc; border-radius: 8px; padding: 10px; }
.bwhq-capability dt { color: #637087; font-size: .75rem; font-weight: 700; text-transform: uppercase; }
.bwhq-capability dd { margin: 3px 0 0; overflow-wrap: anywhere; }
.bwhq-workspace { color: var(--catalog-ink, #172033); width: 100%; }
.bwhq-workspace__header { align-items: center; border-bottom: 1px solid var(--catalog-border, #dce2ea); display: flex; justify-content: space-between; padding: 16px 24px; }
.bwhq-workspace__header p, .bwhq-workspace__header h1 { margin: 0; }
.bwhq-workspace__columns { display: grid; grid-template-columns: minmax(220px, 280px) minmax(0, 1fr) minmax(220px, 280px); min-height: 640px; }
.bwhq-workspace__menu, .bwhq-workspace__main, .bwhq-workspace__context { padding: 20px; }
.bwhq-workspace__menu { border-right: 1px solid var(--catalog-border, #dce2ea); }
.bwhq-workspace__context { border-left: 1px solid var(--catalog-border, #dce2ea); }
.bwhq-app-menu ul { list-style: none; margin: 0; padding: 0; }
.bwhq-app-menu li { margin: 4px 0; }
.bwhq-app-menu a, .bwhq-app-menu span { border-radius: 7px; color: inherit; display: block; padding: 8px 10px; text-decoration: none; }
.bwhq-app-menu a[aria-current="page"] { background: #eef2ff; color: #243da2; font-weight: 700; }
.bwhq-data-list, .bwhq-headless-list, .bwhq-native-frame { border: 1px solid var(--catalog-border, #dce2ea); border-radius: 10px; padding: 16px; }
.bwhq-data-list ul, .bwhq-headless-list ul { list-style: none; margin: 0; padding: 0; }
.bwhq-headless-list button { align-items: start; background: transparent; border: 0; border-bottom: 1px solid var(--catalog-border, #dce2ea); cursor: pointer; display: grid; gap: 3px; padding: 10px 0; text-align: left; width: 100%; }
.bwhq-headless-list button span { color: #637087; }
.bwhq-runtime-page { min-width: 0; width: 100%; }
.bwhq-headless-resource, .bwhq-headless-directory { color: var(--catalog-ink, #172033); display: grid; gap: 16px; width: 100%; }
.bwhq-headless-resource > header, .bwhq-headless-directory > header { align-items: end; display: flex; gap: 20px; justify-content: space-between; }
.bwhq-headless-resource header p, .bwhq-headless-resource header h2, .bwhq-headless-directory h1 { margin: 0; }
.bwhq-headless-resource label, .bwhq-headless-directory label { display: grid; gap: 4px; }
.bwhq-headless-resource input, .bwhq-headless-directory input { border: 1px solid var(--catalog-border, #dce2ea); border-radius: 7px; font: inherit; padding: 8px 10px; }
.bwhq-headless-resource > ul { display: grid; gap: 0; list-style: none; margin: 0; padding: 0; }
.bwhq-headless-resource > ul li { border-bottom: 1px solid var(--catalog-border, #dce2ea); display: grid; padding: 10px 0; }
.bwhq-headless-resource > ul li span { color: #637087; }
.bwhq-headless-resource > nav { align-items: center; display: flex; gap: 10px; justify-content: center; }
.bwhq-headless-resource form { border: 1px solid var(--catalog-border, #dce2ea); border-radius: 10px; display: grid; gap: 10px; padding: 16px; }
.bwhq-headless-resource form h3 { margin: 0; }
.bwhq-headless-directory details { border: 1px solid var(--catalog-border, #dce2ea); border-radius: 8px; padding: 12px; }
.bwhq-headless-directory summary { cursor: pointer; display: flex; justify-content: space-between; }
.bwhq-headless-directory table { border-collapse: collapse; margin-top: 10px; width: 100%; }
.bwhq-headless-directory th, .bwhq-headless-directory td { border-bottom: 1px solid var(--catalog-border, #dce2ea); padding: 8px; text-align: left; vertical-align: top; }
@media (max-width: 1050px) { .bwhq-workspace__columns { grid-template-columns: 240px minmax(0, 1fr); } .bwhq-workspace__context { border-left: 0; border-top: 1px solid var(--catalog-border, #dce2ea); grid-column: 1 / -1; } }
@media (max-width: 720px) { .bwhq-capability dl { grid-template-columns: 1fr; } .bwhq-workspace__columns { display: block; } .bwhq-workspace__menu { border-bottom: 1px solid var(--catalog-border, #dce2ea); border-right: 0; } .bwhq-headless-resource > header, .bwhq-headless-directory > header { align-items: stretch; flex-direction: column; } .bwhq-headless-directory { overflow-x: auto; } }
```

**All first-class capability components**

```
import { buildWithHQCatalog, type CatalogCapability } from "./catalog-data.generated";

export interface FirstClassCapabilityProps {
  readonly capability: CatalogCapability;
  readonly styled?: boolean;
  readonly showSecurity?: boolean;
}

const implementationLabel = (capability: CatalogCapability): string => {
  if (capability.implementation.kind === "page-module") return "Native page module";
  if (capability.implementation.kind === "product-solution-renderer") return "Read-only discovery page";
  if (capability.implementation.kind === "shell-and-page-component") return "Tenant shell and native page component";
  if (capability.implementation.kind === "shell-component") return "Tenant shell component";
  return "Background platform capability";
};

export const FirstClassCapability = ({ capability, styled = false, showSecurity = true }: FirstClassCapabilityProps) => (
  <article className={styled ? "bwhq-capability" : undefined} data-capability={capability.slug}>
    <header>
      <p>{capability.experience}</p>
      <h2>{capability.title}</h2>
      <span>{implementationLabel(capability)}</span>
    </header>
    <p>{capability.summary}</p>
    <h3>What developers can build</h3>
    <ul>{capability.capabilities.map((item) => <li key={item}>{item}</li>)}</ul>
    <h3>Common uses</h3>
    <ul>{capability.common_uses.map((item) => <li key={item}>{item}</li>)}</ul>
    <dl>
      <div><dt>Page block</dt><dd>{capability.implementation.native_component_key ?? "Not a page block"}</dd></div>
      <div><dt>React</dt><dd>{capability.implementation.react_components.map((item) => item.component).join(", ") || "No interactive renderer is currently exposed"}</dd></div>
      <div><dt>API roots</dt><dd>{capability.implementation.api_base_paths.join(", ") || "Background service contracts"}</dd></div>
    </dl>
    {showSecurity && <details><summary>Security boundary</summary><p>{capability.security}</p></details>}
    <p><a href={capability.documentation_path}>Implementation guide for {capability.title}</a></p>
  </article>
);

export const UnstyledFirstClassCapability = (props: Omit<FirstClassCapabilityProps, "styled">) =>
  <FirstClassCapability {...props} styled={false} />;

export const StyledFirstClassCapability = (props: Omit<FirstClassCapabilityProps, "styled">) =>
  <FirstClassCapability {...props} styled />;

export const firstClassCapabilities = buildWithHQCatalog.first_class_capabilities;

export const UnstyledConnectedWorkCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "connected-work")!} />;
export const StyledConnectedWorkCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "connected-work")!} />;
export const UnstyledKnowledgeFinderCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "knowledge-finder")!} />;
export const StyledKnowledgeFinderCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "knowledge-finder")!} />;
export const UnstyledUniversalInboxCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "universal-inbox")!} />;
export const StyledUniversalInboxCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "universal-inbox")!} />;
export const UnstyledChecklistsSignoffsCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "checklists-signoffs")!} />;
export const StyledChecklistsSignoffsCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "checklists-signoffs")!} />;
export const UnstyledGoclawCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "goclaw")!} />;
export const StyledGoclawCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "goclaw")!} />;
export const UnstyledAiInsightsCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "ai-insights")!} />;
export const StyledAiInsightsCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "ai-insights")!} />;
export const UnstyledContactsCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "contacts")!} />;
export const StyledContactsCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "contacts")!} />;
export const UnstyledWorkOrdersCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "work-orders")!} />;
export const StyledWorkOrdersCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "work-orders")!} />;
export const UnstyledReservationsCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "reservations")!} />;
export const StyledReservationsCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "reservations")!} />;
export const UnstyledCalendarCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "calendar")!} />;
export const StyledCalendarCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "calendar")!} />;
export const UnstyledFilesCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "files")!} />;
export const StyledFilesCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "files")!} />;
export const UnstyledConversationsCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "conversations")!} />;
export const StyledConversationsCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "conversations")!} />;
export const UnstyledCompanyNewsCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "company-news")!} />;
export const StyledCompanyNewsCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "company-news")!} />;
export const UnstyledKnowledgeCoreCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "knowledge-core")!} />;
export const StyledKnowledgeCoreCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "knowledge-core")!} />;
export const UnstyledWebLinksCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "web-links")!} />;
export const StyledWebLinksCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "web-links")!} />;
export const UnstyledChatRoomsCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "chat-rooms")!} />;
export const StyledChatRoomsCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "chat-rooms")!} />;
export const UnstyledDiscussionBoardsCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "discussion-boards")!} />;
export const StyledDiscussionBoardsCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "discussion-boards")!} />;
export const UnstyledMailReaderCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "mail-reader")!} />;
export const StyledMailReaderCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "mail-reader")!} />;
export const UnstyledFavoritesCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "favorites")!} />;
export const StyledFavoritesCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "favorites")!} />;
export const UnstyledNotificationsCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "notifications")!} />;
export const StyledNotificationsCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "notifications")!} />;
export const UnstyledDynamicRecordsCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "dynamic-records")!} />;
export const StyledDynamicRecordsCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "dynamic-records")!} />;
export const UnstyledActiveWorkplaceCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "active-workplace")!} />;
export const StyledActiveWorkplaceCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "active-workplace")!} />;
export const UnstyledRecordRelationsCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "record-relations")!} />;
export const StyledRecordRelationsCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "record-relations")!} />;
export const UnstyledRecordActivityCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "record-activity")!} />;
export const StyledRecordActivityCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "record-activity")!} />;
export const UnstyledGlobalSearchCapability = () => <UnstyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "global-search")!} />;
export const StyledGlobalSearchCapability = () => <StyledFirstClassCapability capability={firstClassCapabilities.find((item) => item.slug === "global-search")!} />;
```

**All native module block exports**

```
import type { RuntimePageBlock } from "@buildwithhq/page-runtime";

export interface NativeModuleRecipe {
  readonly moduleKey: string | null;
  readonly componentKey: string;
  readonly rendererKey: string;
  readonly displayName: string;
  readonly apiBasePath: string;
  readonly unstyledBlock: RuntimePageBlock;
  readonly styledComposition: RuntimePageBlock;
}

export const nativeModuleRecipes = [
  {
    "moduleKey": "goclaw",
    "componentKey": "module.goclaw",
    "rendererKey": "module.goclaw",
    "displayName": "Goclaw",
    "apiBasePath": "/api/goclaw/approvals",
    "unstyledBlock": {
      "_id": "goclaw-module",
      "_type": "module.goclaw",
      "props": {
        "title": "Goclaw"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "goclaw-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "goclaw-heading",
          "_type": "core.text",
          "_parent": "goclaw-section",
          "props": {
            "text": "Goclaw",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "goclaw-module",
          "_type": "module.goclaw",
          "_parent": "goclaw-section",
          "props": {
            "title": "Goclaw"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "universal-inbox",
    "componentKey": "core.universal-inbox",
    "rendererKey": "core.universal-inbox",
    "displayName": "Universal Inbox",
    "apiBasePath": "/api/inbox",
    "unstyledBlock": {
      "_id": "core-universal-inbox-module",
      "_type": "core.universal-inbox",
      "props": {
        "title": "Universal Inbox"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "core-universal-inbox-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "core-universal-inbox-heading",
          "_type": "core.text",
          "_parent": "core-universal-inbox-section",
          "props": {
            "text": "Universal Inbox",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "core-universal-inbox-module",
          "_type": "core.universal-inbox",
          "_parent": "core-universal-inbox-section",
          "props": {
            "title": "Universal Inbox"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "active-workplace",
    "componentKey": "module.active-workplace",
    "rendererKey": "module.active-workplace",
    "displayName": "Active Workplace",
    "apiBasePath": "/api/modules/active-workplace",
    "unstyledBlock": {
      "_id": "active-workplace-module",
      "_type": "module.active-workplace",
      "props": {
        "title": "Active Workplace"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "active-workplace-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "active-workplace-heading",
          "_type": "core.text",
          "_parent": "active-workplace-section",
          "props": {
            "text": "Active Workplace",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "active-workplace-module",
          "_type": "module.active-workplace",
          "_parent": "active-workplace-section",
          "props": {
            "title": "Active Workplace"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "ai_insights",
    "componentKey": "module.ai-insights",
    "rendererKey": "module.ai-insights",
    "displayName": "Ai Insights",
    "apiBasePath": "/api/modules/ai-insights",
    "unstyledBlock": {
      "_id": "ai-insights-module",
      "_type": "module.ai-insights",
      "props": {
        "title": "Ai Insights"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "ai-insights-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "ai-insights-heading",
          "_type": "core.text",
          "_parent": "ai-insights-section",
          "props": {
            "text": "Ai Insights",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "ai-insights-module",
          "_type": "module.ai-insights",
          "_parent": "ai-insights-section",
          "props": {
            "title": "Ai Insights"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "calendar",
    "componentKey": "module.calendar",
    "rendererKey": "module.calendar",
    "displayName": "Calendar",
    "apiBasePath": "/api/modules/calendar",
    "unstyledBlock": {
      "_id": "calendar-module",
      "_type": "module.calendar",
      "props": {
        "title": "Calendar"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "calendar-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "calendar-heading",
          "_type": "core.text",
          "_parent": "calendar-section",
          "props": {
            "text": "Calendar",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "calendar-module",
          "_type": "module.calendar",
          "_parent": "calendar-section",
          "props": {
            "title": "Calendar"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "chat-rooms",
    "componentKey": "module.chat-rooms",
    "rendererKey": "module.chat-rooms",
    "displayName": "Chat Rooms",
    "apiBasePath": "/api/modules/chat-rooms",
    "unstyledBlock": {
      "_id": "chat-rooms-module",
      "_type": "module.chat-rooms",
      "props": {
        "title": "Chat Rooms"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "chat-rooms-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "chat-rooms-heading",
          "_type": "core.text",
          "_parent": "chat-rooms-section",
          "props": {
            "text": "Chat Rooms",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "chat-rooms-module",
          "_type": "module.chat-rooms",
          "_parent": "chat-rooms-section",
          "props": {
            "title": "Chat Rooms"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "checklists_signoffs",
    "componentKey": "module.checklists-signoffs",
    "rendererKey": "module.checklists-signoffs",
    "displayName": "Checklists Signoffs",
    "apiBasePath": "/api/modules/checklists-signoffs",
    "unstyledBlock": {
      "_id": "checklists-signoffs-module",
      "_type": "module.checklists-signoffs",
      "props": {
        "title": "Checklists Signoffs"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "checklists-signoffs-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "checklists-signoffs-heading",
          "_type": "core.text",
          "_parent": "checklists-signoffs-section",
          "props": {
            "text": "Checklists Signoffs",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "checklists-signoffs-module",
          "_type": "module.checklists-signoffs",
          "_parent": "checklists-signoffs-section",
          "props": {
            "title": "Checklists Signoffs"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "company-news",
    "componentKey": "module.company-news",
    "rendererKey": "module.company-news",
    "displayName": "Company News",
    "apiBasePath": "/api/modules/company-news",
    "unstyledBlock": {
      "_id": "company-news-module",
      "_type": "module.company-news",
      "props": {
        "title": "Company News"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "company-news-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "company-news-heading",
          "_type": "core.text",
          "_parent": "company-news-section",
          "props": {
            "text": "Company News",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "company-news-module",
          "_type": "module.company-news",
          "_parent": "company-news-section",
          "props": {
            "title": "Company News"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "contacts",
    "componentKey": "module.contacts",
    "rendererKey": "module.contacts",
    "displayName": "Contacts",
    "apiBasePath": "/api/modules/contacts",
    "unstyledBlock": {
      "_id": "contacts-module",
      "_type": "module.contacts",
      "props": {
        "title": "Contacts"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "contacts-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "contacts-heading",
          "_type": "core.text",
          "_parent": "contacts-section",
          "props": {
            "text": "Contacts",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "contacts-module",
          "_type": "module.contacts",
          "_parent": "contacts-section",
          "props": {
            "title": "Contacts"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "conversations",
    "componentKey": "module.conversations",
    "rendererKey": "module.conversations",
    "displayName": "Conversations",
    "apiBasePath": "/api/modules/conversations",
    "unstyledBlock": {
      "_id": "conversations-module",
      "_type": "module.conversations",
      "props": {
        "title": "Conversations"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "conversations-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "conversations-heading",
          "_type": "core.text",
          "_parent": "conversations-section",
          "props": {
            "text": "Conversations",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "conversations-module",
          "_type": "module.conversations",
          "_parent": "conversations-section",
          "props": {
            "title": "Conversations"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "discussion-boards",
    "componentKey": "module.discussion-boards",
    "rendererKey": "module.discussion-boards",
    "displayName": "Discussion Boards",
    "apiBasePath": "/api/modules/discussion-boards",
    "unstyledBlock": {
      "_id": "discussion-boards-module",
      "_type": "module.discussion-boards",
      "props": {
        "title": "Discussion Boards"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "discussion-boards-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "discussion-boards-heading",
          "_type": "core.text",
          "_parent": "discussion-boards-section",
          "props": {
            "text": "Discussion Boards",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "discussion-boards-module",
          "_type": "module.discussion-boards",
          "_parent": "discussion-boards-section",
          "props": {
            "title": "Discussion Boards"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": null,
    "componentKey": "module.dynamic-records",
    "rendererKey": "module.dynamic-records",
    "displayName": "Dynamic Records",
    "apiBasePath": "/api/modules/dynamic",
    "unstyledBlock": {
      "_id": "dynamic-records-module",
      "_type": "module.dynamic-records",
      "props": {
        "title": "Dynamic Records"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "dynamic-records-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "dynamic-records-heading",
          "_type": "core.text",
          "_parent": "dynamic-records-section",
          "props": {
            "text": "Dynamic Records",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "dynamic-records-module",
          "_type": "module.dynamic-records",
          "_parent": "dynamic-records-section",
          "props": {
            "title": "Dynamic Records"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "favorites",
    "componentKey": "module.favorites",
    "rendererKey": "module.favorites",
    "displayName": "Favorites",
    "apiBasePath": "/api/modules/favorites",
    "unstyledBlock": {
      "_id": "favorites-module",
      "_type": "module.favorites",
      "props": {
        "title": "Favorites"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "favorites-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "favorites-heading",
          "_type": "core.text",
          "_parent": "favorites-section",
          "props": {
            "text": "Favorites",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "favorites-module",
          "_type": "module.favorites",
          "_parent": "favorites-section",
          "props": {
            "title": "Favorites"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "files",
    "componentKey": "module.files",
    "rendererKey": "module.files",
    "displayName": "Files",
    "apiBasePath": "/api/modules/files",
    "unstyledBlock": {
      "_id": "files-module",
      "_type": "module.files",
      "props": {
        "title": "Files"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "files-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "files-heading",
          "_type": "core.text",
          "_parent": "files-section",
          "props": {
            "text": "Files",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "files-module",
          "_type": "module.files",
          "_parent": "files-section",
          "props": {
            "title": "Files"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "global-search",
    "componentKey": "module.global-search",
    "rendererKey": "module.global-search",
    "displayName": "Global Search",
    "apiBasePath": "/api/modules/global-search",
    "unstyledBlock": {
      "_id": "global-search-module",
      "_type": "module.global-search",
      "props": {
        "title": "Global Search"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "global-search-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "global-search-heading",
          "_type": "core.text",
          "_parent": "global-search-section",
          "props": {
            "text": "Global Search",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "global-search-module",
          "_type": "module.global-search",
          "_parent": "global-search-section",
          "props": {
            "title": "Global Search"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "knowledge-articles",
    "componentKey": "module.knowledge-articles",
    "rendererKey": "module.knowledge-articles",
    "displayName": "Knowledge Articles",
    "apiBasePath": "/api/modules/knowledge-articles",
    "unstyledBlock": {
      "_id": "knowledge-articles-module",
      "_type": "module.knowledge-articles",
      "props": {
        "title": "Knowledge Articles"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "knowledge-articles-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "knowledge-articles-heading",
          "_type": "core.text",
          "_parent": "knowledge-articles-section",
          "props": {
            "text": "Knowledge Articles",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "knowledge-articles-module",
          "_type": "module.knowledge-articles",
          "_parent": "knowledge-articles-section",
          "props": {
            "title": "Knowledge Articles"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "mail-reader",
    "componentKey": "module.mail-reader",
    "rendererKey": "module.mail-reader",
    "displayName": "Mail Reader",
    "apiBasePath": "/api/modules/mail-reader",
    "unstyledBlock": {
      "_id": "mail-reader-module",
      "_type": "module.mail-reader",
      "props": {
        "title": "Mail Reader"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "mail-reader-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "mail-reader-heading",
          "_type": "core.text",
          "_parent": "mail-reader-section",
          "props": {
            "text": "Mail Reader",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "mail-reader-module",
          "_type": "module.mail-reader",
          "_parent": "mail-reader-section",
          "props": {
            "title": "Mail Reader"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "notifications",
    "componentKey": "module.notifications",
    "rendererKey": "module.notifications",
    "displayName": "Notifications",
    "apiBasePath": "/api/modules/notifications",
    "unstyledBlock": {
      "_id": "notifications-module",
      "_type": "module.notifications",
      "props": {
        "title": "Notifications"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "notifications-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "notifications-heading",
          "_type": "core.text",
          "_parent": "notifications-section",
          "props": {
            "text": "Notifications",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "notifications-module",
          "_type": "module.notifications",
          "_parent": "notifications-section",
          "props": {
            "title": "Notifications"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "record-activity",
    "componentKey": "module.record-activity",
    "rendererKey": "module.record-activity",
    "displayName": "Record Activity",
    "apiBasePath": "/api/modules/record-activity",
    "unstyledBlock": {
      "_id": "record-activity-module",
      "_type": "module.record-activity",
      "props": {
        "title": "Record Activity"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "record-activity-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "record-activity-heading",
          "_type": "core.text",
          "_parent": "record-activity-section",
          "props": {
            "text": "Record Activity",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "record-activity-module",
          "_type": "module.record-activity",
          "_parent": "record-activity-section",
          "props": {
            "title": "Record Activity"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "record-graph",
    "componentKey": "module.record-graph",
    "rendererKey": "module.record-graph",
    "displayName": "Record Graph",
    "apiBasePath": "/api/modules/record-graph",
    "unstyledBlock": {
      "_id": "record-graph-module",
      "_type": "module.record-graph",
      "props": {
        "title": "Record Graph"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "record-graph-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "record-graph-heading",
          "_type": "core.text",
          "_parent": "record-graph-section",
          "props": {
            "text": "Record Graph",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "record-graph-module",
          "_type": "module.record-graph",
          "_parent": "record-graph-section",
          "props": {
            "title": "Record Graph"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "reservations",
    "componentKey": "module.reservations",
    "rendererKey": "module.reservations",
    "displayName": "Reservations",
    "apiBasePath": "/api/modules/reservations",
    "unstyledBlock": {
      "_id": "reservations-module",
      "_type": "module.reservations",
      "props": {
        "title": "Reservations"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "reservations-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "reservations-heading",
          "_type": "core.text",
          "_parent": "reservations-section",
          "props": {
            "text": "Reservations",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "reservations-module",
          "_type": "module.reservations",
          "_parent": "reservations-section",
          "props": {
            "title": "Reservations"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "web-links",
    "componentKey": "module.web-links",
    "rendererKey": "module.web-links",
    "displayName": "Web Links",
    "apiBasePath": "/api/modules/web-links",
    "unstyledBlock": {
      "_id": "web-links-module",
      "_type": "module.web-links",
      "props": {
        "title": "Web Links"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "web-links-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "web-links-heading",
          "_type": "core.text",
          "_parent": "web-links-section",
          "props": {
            "text": "Web Links",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "web-links-module",
          "_type": "module.web-links",
          "_parent": "web-links-section",
          "props": {
            "title": "Web Links"
          },
          "children": []
        }
      ]
    }
  },
  {
    "moduleKey": "work_orders",
    "componentKey": "module.work-orders",
    "rendererKey": "module.work-orders",
    "displayName": "Work Orders",
    "apiBasePath": "/api/modules/work-orders",
    "unstyledBlock": {
      "_id": "work-orders-module",
      "_type": "module.work-orders",
      "props": {
        "title": "Work Orders"
      },
      "children": []
    },
    "styledComposition": {
      "_id": "work-orders-section",
      "_type": "core.container",
      "props": {
        "layout": "stack"
      },
      "children": [
        {
          "_id": "work-orders-heading",
          "_type": "core.text",
          "_parent": "work-orders-section",
          "props": {
            "text": "Work Orders",
            "variant": "heading",
            "align": "left"
          },
          "children": []
        },
        {
          "_id": "work-orders-module",
          "_type": "module.work-orders",
          "_parent": "work-orders-section",
          "props": {
            "title": "Work Orders"
          },
          "children": []
        }
      ]
    }
  }
] as const satisfies readonly NativeModuleRecipe[];

export const GoclawUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.goclaw")!.unstyledBlock;
export const GoclawStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.goclaw")!.styledComposition;
export const CoreUniversalInboxUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "core.universal-inbox")!.unstyledBlock;
export const CoreUniversalInboxStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "core.universal-inbox")!.styledComposition;
export const ActiveWorkplaceUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.active-workplace")!.unstyledBlock;
export const ActiveWorkplaceStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.active-workplace")!.styledComposition;
export const AiInsightsUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.ai-insights")!.unstyledBlock;
export const AiInsightsStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.ai-insights")!.styledComposition;
export const CalendarUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.calendar")!.unstyledBlock;
export const CalendarStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.calendar")!.styledComposition;
export const ChatRoomsUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.chat-rooms")!.unstyledBlock;
export const ChatRoomsStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.chat-rooms")!.styledComposition;
export const ChecklistsSignoffsUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.checklists-signoffs")!.unstyledBlock;
export const ChecklistsSignoffsStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.checklists-signoffs")!.styledComposition;
export const CompanyNewsUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.company-news")!.unstyledBlock;
export const CompanyNewsStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.company-news")!.styledComposition;
export const ContactsUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.contacts")!.unstyledBlock;
export const ContactsStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.contacts")!.styledComposition;
export const ConversationsUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.conversations")!.unstyledBlock;
export const ConversationsStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.conversations")!.styledComposition;
export const DiscussionBoardsUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.discussion-boards")!.unstyledBlock;
export const DiscussionBoardsStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.discussion-boards")!.styledComposition;
export const DynamicRecordsUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.dynamic-records")!.unstyledBlock;
export const DynamicRecordsStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.dynamic-records")!.styledComposition;
export const FavoritesUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.favorites")!.unstyledBlock;
export const FavoritesStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.favorites")!.styledComposition;
export const FilesUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.files")!.unstyledBlock;
export const FilesStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.files")!.styledComposition;
export const GlobalSearchUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.global-search")!.unstyledBlock;
export const GlobalSearchStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.global-search")!.styledComposition;
export const KnowledgeArticlesUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.knowledge-articles")!.unstyledBlock;
export const KnowledgeArticlesStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.knowledge-articles")!.styledComposition;
export const MailReaderUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.mail-reader")!.unstyledBlock;
export const MailReaderStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.mail-reader")!.styledComposition;
export const NotificationsUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.notifications")!.unstyledBlock;
export const NotificationsStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.notifications")!.styledComposition;
export const RecordActivityUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.record-activity")!.unstyledBlock;
export const RecordActivityStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.record-activity")!.styledComposition;
export const RecordGraphUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.record-graph")!.unstyledBlock;
export const RecordGraphStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.record-graph")!.styledComposition;
export const ReservationsUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.reservations")!.unstyledBlock;
export const ReservationsStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.reservations")!.styledComposition;
export const WebLinksUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.web-links")!.unstyledBlock;
export const WebLinksStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.web-links")!.styledComposition;
export const WorkOrdersUnstyledBlock = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.work-orders")!.unstyledBlock;
export const WorkOrdersStyledComposition = nativeModuleRecipes.find((recipe) => recipe.componentKey === "module.work-orders")!.styledComposition;
```

## Regenerate and verify

```
python catalog-generator/generate_catalog.py
python catalog-generator/generate_catalog.py --check
apps\tenant-runtime\node_modules\.bin\tsc.cmd -p catalog-generator\generated\tsconfig.json

# Optional: merge dev/test route-to-SQL observations
python catalog-generator/generate_catalog.py --observations C:\absolute\path\observations.jsonl
```

Enable runtime observation only in a disposable Development/Test tenant-runtime process with an absolute `CatalogCapture:OutputPath`. The capture feature refuses Production and writes no request data, identity, host, token, SQL parameters, result, or connection details.

Important

A generated catalog is an implementation inventory, not an authorization bypass, production capacity claim, penetration-test result, or proof that every route was exercised. Keep negative-path, cross-tenant, concurrency, accessibility, browser and failure-recovery tests alongside it.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/react-component-catalog.html).

---
title: "Professional Template Foundation"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/professional-template-foundation.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Professional Template Foundation

Build polished, responsive SaaS pages from registry-backed components, copyable compositions, token-safe themes and server-scoped data bindings.

## In brief

- **Components:** 18
- **Page compositions:** 7
- **Theme presets:** 3
- **Data scope:** Server enforced

The Professional Template Foundation is a registry-backed starting point for polished BuildWithHQ applications. Developer Kit 1.20.70 combines the eleven Foundation components with seven interactive API presentation components, seven complete page compositions, a named icon vocabulary, flexible responsive grids, 25 first-class module presentation recipes, eighteen contract-backed product API recipes, portable and full runtime page embedding, app-wide organization/user lifecycle webhooks, a complete webhook receiver and background-job poller, marketplace service discovery and per-app OpenAPI, a tested pagination/filtering/rate-limit policy, the complete API Map and recursive Record Graph guide, governed Skills, durable REST/MCP installed-service Tasks, three theme presets, separate draft/live page credentials, an HTML-to-Puck converter, a self-contained local Puck binding editor, a safe account-overlay sync tool, a tested DeepSeek Harness MCP setup, and an exact tenant-provisioning and authentication map without creating a second renderer, a second permission system, or a client-side data layer.

The current kit includes separate secured Contacts and Global Search counts, fast-row defaults, and an executable progressive-loading SDK example with cancellation and error-state tests. Search runs before the 5,000-match browsing limit; full authorized counts remain uncapped. See [progressive loading, searchable paging and exact counts](../api/progressive-loading-and-counts.html).

[Download kit](#developer-kit) [Designer capabilities](#designer-capabilities) [How it works](#how-it-works) [Component keys](#components) [Copy pages](#pages) [Edit in Puck](#puck) [Choose a theme](#themes) [Bind live data](#bindings) [Publish](#publish) [Limits and tests](#limits)

Note

The page compositions work as immediate static previews. Live values must use a registered server-side binding. Existing SaaS databases need the reviewed component-registry release migration before these blocks appear in Puck; builders must never insert registry or theme rows directly.

## Download the Builder Developer Kit

[**Download the shared BuildWithHQ / API43 Developer Kit 1.20.70**](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip)  (1162.7 KiB). Verify SHA-256 `c31a26f93b948d5f703769eed60e72c346f9b92f6bdd1b424efcb95f08a1574e`, or download the adjacent [checksum file](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip.sha256).

A builder working entirely in BuildWithHQ does not need the repository or its maintainer test commands. Install the exact published Template Library version, open its pages in Puck, and customize them. Download the kit when you want standalone styled and unstyled React, canonical page and theme JSON, the public capability catalog, OpenAPI, the server-side TypeScript SDK, or MCP/CLI setup material.

Version 1.20.16 activates durable installed-service Tasks through typed REST/SDK status and cancellation plus negotiated MCP `tasks/get`, `tasks/update`, and `tasks/cancel`. Every task call reauthorizes and cancellation reports requested, effective, or too-late without claiming to undo committed work. Version 1.20.15 added governed Skills discovery, digest-bound exact resources, and delegated-owner GoClaw assignment. Skills and Tasks extension methods remain distinct from the curated MCP tool map, and declarations never grant authority. Version 1.20.14 added organization-owned support lanes and SMS ticketing.

The ZIP catalogs 340 published API paths and 422 operations. A trusted API43/ISV server can provision passwordless external users, edit unpublished page JSON with a draft key, publish with a separate live key, issue a narrow `bwu_live_` browser token, embed published pages, and generate a typed client for its installed marketplace endpoints without exposing either app credential.

[Developer Kit 1.20.70 release notes](../api/current-api-contracts.html#developer-kit-12064)  describe the review corrections, OpenAPI-generated contract guidance, four additional SDK page-size guards and packaged verification evidence. Strict request-field validation and the restored Mail Reader routes remain available. [Download the exact release-gate report](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip.gate.json). Historical 1.20.61 corrections and [1.20.60 revision guidance](../api/current-api-contracts.html#developer-kit-12060)  remain available.

**Install and type-check the portable React examples**

```
cd react
npm install
npm run typecheck
```

Run plain `npm install` from the extracted `react/` directory. The shipped npm lock pins React 19.2.8, React types 19.2.18, the Go-based TypeScript compiler 7.0.2, and lucide-react 1.41.0 for verification while the package keeps its React 18-or-19 peer range. The top-level typecheck intentionally excludes `react/native/`; those starters require the official `@buildwithhq/*` packages supplied by an extension workspace.

| Surface | Use | Identity boundary |
| --- | --- | --- |
| **Builder and Puck** | Install, edit, validate and publish template pages. | Short-lived Builder identity and account ownership. |
| **Developer API and MCP** | Operate on one SaaS app's authorized data and integrations. | App-bound credential with `mcp.use` plus each tool's scope. |
| **Headless React** | Paint already-authorized results in a custom interface. | Your server holds the API credential; the browser never does. |

The app-scoped MCP endpoint is `https://api.buildwithhq.com/v1/apps/{saasAppId}/mcp`. Tool discovery is authoritative, and sensitive mutation tools remain absent unless server policy explicitly enables them.

**Copy the MCP connection descriptor**

```
{
  "schemaVersion": 1,
  "name": "BuildWithHQ / API43",
  "transport": "streamable-http",
  "urlTemplate": "https://api.buildwithhq.com/v1/apps/{saasAppId}/mcp",
  "authentication": {
    "type": "bearer",
    "credentialSource": {
      "kind": "environment",
      "name": "BWHQ_API_CREDENTIAL"
    }
  },
  "requiredConfiguration": {
    "saasAppIdEnvironment": "BWHQ_SAAS_APP_ID",
    "minimumScopes": ["mcp.use"],
    "toolScopesAreAdditional": true
  },
  "security": {
    "credentialBoundToExactSaasApp": true,
    "routeAppIsAuthorization": false,
    "physicalRoutingExposed": false,
    "sensitiveMutationsDefaultDenied": true
  }
}
```

**Copy the CLI profile setup**

```
# Install bwhq 0.1.0 from your approved BuildWithHQ package channel first.
# Secrets stay in your environment or secret manager, not in the profile.
bwhq auth profile add `
  --name my-saas `
  --saas-app-id <your-saas-app-id> `
  --base-url https://api.buildwithhq.com `
  --credential-env BWHQ_API_CREDENTIAL `
  --control-plane-base-url https://hello.buildwithhq.com `
  --builder-token-env BWHQ_BUILDER_TOKEN `
  --set-current

bwhq doctor --profile my-saas
bwhq status --profile my-saas
```

Important

The ZIP contains CLI instructions, not a signed bwhq executable. Publish the CLI through an approved package channel as a separate release. Never ask a builder to compile the repository, and never put BWHQ_API_CREDENTIAL or BWHQ_BUILDER_TOKEN in page JSON, React source, a ZIP, or a prompt.

## What designers can do now

Designers can work visually in BuildWithHQ, while React developers can take the same component and page contracts further. The visual layer can be as art-directed as a premium React template without moving identity, authorization or database routing into the browser.

### Build visually

- Build and rearrange responsive pages in Puck without writing React.
- Choose an automatic card grid or an opt-in 12-column canvas, then set each block's desktop, tablet and mobile span from 1 through 12.
- Choose named icons for metrics and navigation; every icon inherits the active theme and unknown names fail closed.
- Compose Container, Text, page headers, cards, statistics, badges, section labels, list rows, bounded tables, accessible charts and explicit empty states.
- Start from complete Dashboard, Queue/List and Record Detail compositions instead of a blank canvas.
- Change color, typography, spacing, borders, radius and light/dark behavior through safe design tokens and the three included theme presets.
- Bind statistics, charts and tables to reviewed server-scoped results, then preview loading, error, empty and populated states.
- Publish a coherent page family as an exact-version template so an installed tenant does not change silently.
- Use the downloadable styled or unstyled React examples when the visual work needs to continue outside Puck.

### How React fits together

- Puck saves canonical page JSON containing stable block identities, registered component keys and validated presentation properties.
- The React renderer maps each registered key to reviewed, statically bundled component code. Catalog metadata never dynamically executes arbitrary code.
- The server derives the SaaS app, account, user, DataRoles and Locations; SQL returns only the permitted result; React simply renders that bounded result.
- Developers can register additional React components, expose only intentional properties to Puck and reuse the existing binding, loading and error contracts.
- A licensed third-party React design can be adapted into registered components without replacing BuildWithHQ authentication, APIs or server-side data scope.

### Reach premium-template visual quality

- Use one deliberate design system for typography, spacing, color, shadows, borders and corner treatments instead of styling each page independently.
- Add richer reviewed blocks such as hero sections, navigation, tabs, timelines, activity feeds, forms, pricing cards, kanban boards and command bars.
- Start with the included named icon vocabulary, then add separately reviewed licensed illustrations, photography and branded empty states to create a distinctive visual language.
- Add restrained hover effects, transitions, skeleton loaders and page motion through normal React and CSS implementation.
- Design desktop, tablet and mobile layouts intentionally, including keyboard behavior, focus states, long content and overflow.
- Design complete loading, empty, error, forbidden and success states rather than only the ideal populated screen.
- Package several art-directed page families over the same secure bindings; a new skin does not require a new database or authorization model.

Tip

The foundation supplies the secure renderer, bindings and reusable design vocabulary. ThemeForest-level polish comes from art direction, licensed assets, thoughtful motion and a broader library of product-specific blocks — all of which can be added without weakening the data boundary.

## 1. How the foundation works

| Layer | What it owns | What it does not own |
| --- | --- | --- |
| **Component Registry** | Stable keys, display names, default props, renderer keys and versions. | Tenant identity, data scope or SQL. |
| **Canonical page JSON** | Stable block IDs, layout, component properties, children and approved binding keys. | Authorization or physical database routing. |
| **SaaS app theme** | Light/dark/system mode and allowlisted `--runtime-*` design tokens. | Arbitrary executable CSS, script or permissions. |
| **Runtime binding resolver** | Maps a registered `bindingKey` to a reviewed, identity-scoped server operation before JSON is returned. | Ad-hoc SQL or browser-selected tenant/account IDs. |
| **Template Library** | Owned page harvest, validation, immutable page/component publication and exact-version installation. | Silently changing an already installed tenant copy. |

At runtime the server resolves the signed-in SaaS app, account, user, DataRoles and Locations. SQL returns only the permitted result. React receives that already-scoped result and paints it. A component never downloads a broad table and filters it in the browser.

## 2. Use the professional component vocabulary

| Component key | Use it for | Main properties |
| --- | --- | --- |
| `core.page-header` | Page title, lead and breadcrumb. | `title`, `lead`, `breadcrumb[]` |
| `core.stat-tile` | One KPI or bounded scalar. | `label`, `value`, `delta`, `direction`, `iconName`, `tone` |
| `core.card` | A titled content group. | `title`, `description`, `tone`, child blocks |
| `core.chart` | An accessible bar or line summary. | `title`, `variant`, `series[]`, `labels[]`, `tone` |
| `core.data-table` | A bounded server-scoped list. | `caption`, `columns[]`, optional static `rows[]` |
| `core.list-row` | Compact recent activity or person/work summaries. | `primary`, `secondary`, `trailing`, `initials`, `tone` |
| `core.badge` | Status and category labels. | `label`, `tone` |
| `core.section-label` | A compact section eyebrow. | `label` |
| `core.empty-state` | An explicit zero-result or missing-proof state. | `title`, `body` |

Use `core.container` with `layout: "stack"`, `"row"` or `"grid"` to compose them. Grid containers default to `gridMode: "auto-fit"`. Select `"twelve-column"` when you want custom proportions, then set child spans under `responsive.desktop.span`, `responsive.tablet.span` and `responsive.mobile.span`. Catalog values outside the reviewed enums or 1-through-12 span range now fail validation with `E016` before publication.

### Interactive API presentation components included in the current kit

| Component key | Use it for | Bounded contract |
| --- | --- | --- |
| `core.metric-strip` | KPI values, deltas and as-of time. | Up to 12 metrics. |
| `core.entity-list` | Names, context, statuses and record navigation. | Up to 100 items. |
| `core.progress-list` | Status distribution, ranked progress and capacity. | Up to 100 items. |
| `core.series-chart` | Interactive bar/line periods with a semantic table. | 5 periods, 8 series, 120 points. |
| `core.presentation-grid` | Typed visible-page rows, local page sorting and declared row actions. | 24 columns, 500 rows and 8 declared actions. |
| `core.task-list` | Checklist-style completion rows with revision-fenced toggles. | Up to 1,000 items. |
| `core.timeline` | Chronological activity, actors and statuses. | Up to 100 items. |

The downloadable `InteractivePresentationComponents.tsx` is semantic and unstyled by default. Pass `styled` and import `interactive-presentation-components.css` for the supplied professional treatment. `BuildWithHQIcons.tsx` exposes the same bounded, theme-aware icon vocabulary without accepting arbitrary SVG or markup. `ControlPanelDashboardExample.tsx` demonstrates mixed 3/3/3/3, 8/4 and 5/7 layouts without declaring any one of them mandatory. `WorkOrderPresentationExample.tsx` shows the live Work Orders composition; `FirstClassModulePresentationExamples.tsx` provides named compositions for all twenty-three cataloged module experiences, backed by six-row fictional design fixtures in `catalog/module-presentation-samples.json`.

### Copy the task and row-action documents

The server emits action keys only when the signed-in user may be offered that operation. React still treats the key as presentation, and the host maps it through a closed handler list to a reviewed API. The API independently rechecks identity, DataRoles, Locations, record scope and concurrency. Unknown action keys must never become dynamic URLs or executable code.

**Task-list presentation document**

```
{
  "presentationVersion": 1,
  "kind": "task-list",
  "title": "Closeout tasks",
  "items": [
    {
      "id": "<checklist-run-item-id>",
      "recordId": "<secured-record-id>",
      "label": "Attach completion photo",
      "description": "Show the finished installation and asset label.",
      "checked": false,
      "revision": 7,
      "toggleActionKey": "checklists-signoffs.item.toggle"
    }
  ]
}
```

**Data-grid declared action document**

```
{
  "presentationVersion": 1,
  "kind": "data-grid",
  "columns": [{ "key": "name", "label": "Name", "type": "text", "align": "left" }],
  "actions": [
    { "key": "contacts.favorite", "label": "Favorite", "tone": "primary" }
  ],
  "rows": [
    { "id": "<contact-id>", "recordId": "<record-id>", "cells": { "name": "Ada Rivera" }, "actionKeys": ["contacts.favorite"] }
  ]
}
```

**Copy the complete allowlisted React action dispatcher**

```
import {
  PresentationGrid,
  TaskList,
  type PresentationActionRequest,
  type PresentationActionResult,
} from "./InteractivePresentationComponents";
import { parseLegoActionReceipt } from "@buildwithhq/page-runtime";

export interface PresentationActionExampleProps {
  readonly blockId: string;
  readonly data: unknown;
  readonly getCsrfToken: () => Promise<string>;
  /** Refetch the same server-scoped binding that supplied data. */
  readonly loadData: () => Promise<unknown>;
  readonly pageKey: string;
  readonly styled?: boolean;
}

const mutationError = async (response: Response, operation: string): Promise<Error> => {
  let correlationId = response.headers.get("x-correlation-id") ?? undefined;
  try {
    const body = await response.json() as { correlationId?: unknown };
    if (typeof body.correlationId === "string") correlationId = body.correlationId;
  } catch {
    // The stable status and optional response header are sufficient for a safe error.
  }
  return new Error(`${operation} failed (${response.status})${correlationId ? `; correlation ${correlationId}` : ""}`);
};

/**
 * Submit only a server-issued action ID through the fixed Lego broker route.
 * The saved page/block and current authorized catalog are re-resolved by the
 * tenant runtime; neither this example nor page JSON selects implementation.
 */
export const createPresentationActionBroker = (
  getCsrfToken: () => Promise<string>,
  pageKey: string,
  blockId: string,
): ((request: PresentationActionRequest) => Promise<PresentationActionResult>) =>
  async (request) => {
    const response = await fetch("/api/runtime/lego/actions", {
      method: "POST",
      credentials: "same-origin",
      headers: { "Content-Type": "application/json", "X-CSRF-Token": await getCsrfToken() },
      body: JSON.stringify({
        contractVersion: 1,
        pageKey,
        blockId,
        actionId: request.actionId,
        recordId: request.recordId,
        expectedRevision: request.expectedRevision,
        values: request.values,
      }),
    });
    if (!response.ok) throw await mutationError(response, "Lego action");
    const receipt = parseLegoActionReceipt(await response.json(), request.actionId);
    return {
      conflict: receipt.conflict === true,
      refreshBindingId: receipt.refreshBindingId,
      revision: receipt.revision,
    };
  };

export const CloseoutTasks = ({ blockId, data, getCsrfToken, loadData, pageKey, styled = false }: PresentationActionExampleProps) => (
  <TaskList data={data} styled={styled} onAction={createPresentationActionBroker(getCsrfToken, pageKey, blockId)} onRefreshData={loadData} />
);

export const ContactActionGrid = ({ blockId, data, getCsrfToken, loadData, pageKey, styled = false }: PresentationActionExampleProps) => (
  <PresentationGrid data={data} styled={styled} onAction={createPresentationActionBroker(getCsrfToken, pageKey, blockId)} onRefreshData={loadData} />
);
```

The same compiling `onAction` example is included as `react/PresentationActionExample.tsx`. It maps only the reviewed Contacts favorite and checklist-item toggle APIs. The checklist callback returns the new revision so a second toggle cannot accidentally reuse a stale concurrency token. Contacts writes request a refetch because the row's available favorite action changes. A checklist HTTP 409 requests the same scoped document again and displays the other session's authoritative value; it does not retry stale state. Without `onAction`, task checkboxes are disabled and row-action buttons are not rendered.

## 3. Start from a complete page composition

Each source below is canonical BuildWithHQ page content. The dashboard demonstrates KPIs, a chart and activity. The queue demonstrates status, a bounded table and the correct empty state. The record page is a base for Files, Conversations, Checklists, Workflow, Record Activity and other first-class blocks. The control-panel showcase demonstrates several responsive proportions and visual rhythms. The live action page combines checklist toggles and Contacts favorites through real API contracts; its page JSON still contains no database or authorization identity.

**Professional dashboard - copy the complete page JSON**

```
{
  "blocks": [
    {
      "_id": "professional-dashboard-header",
      "_type": "core.page-header",
      "props": {
        "title": "Operations overview",
        "lead": "A focused view of the work, service level, and team activity that need attention today.",
        "breadcrumb": ["Operations", "Overview"]
      }
    },
    {
      "_id": "professional-dashboard-stats",
      "_type": "core.container",
      "props": { "layout": "grid" },
      "children": [
        {
          "_id": "professional-dashboard-stat-open",
          "_type": "core.stat-tile",
          "props": { "label": "Open work", "value": "128", "delta": "12 this week", "direction": "up", "tone": "primary" }
        },
        {
          "_id": "professional-dashboard-stat-due",
          "_type": "core.stat-tile",
          "props": { "label": "Due today", "value": "17", "delta": "4 at risk", "direction": "down", "tone": "warning" }
        },
        {
          "_id": "professional-dashboard-stat-sla",
          "_type": "core.stat-tile",
          "props": { "label": "Within service level", "value": "96%", "delta": "2.4%", "direction": "up", "tone": "success" }
        },
        {
          "_id": "professional-dashboard-stat-waiting",
          "_type": "core.stat-tile",
          "props": { "label": "Waiting on customer", "value": "23", "tone": "neutral" }
        }
      ]
    },
    {
      "_id": "professional-dashboard-detail-grid",
      "_type": "core.container",
      "props": { "layout": "grid" },
      "children": [
        {
          "_id": "professional-dashboard-trend-card",
          "_type": "core.card",
          "props": { "title": "Work completed", "description": "Six-week throughput from the authorized page scope.", "tone": "primary" },
          "children": [
            {
              "_id": "professional-dashboard-trend-chart",
              "_type": "core.chart",
              "props": {
                "title": "Completed work by week",
                "variant": "line",
                "tone": "primary",
                "series": [38, 45, 42, 56, 61, 73],
                "labels": ["W1", "W2", "W3", "W4", "W5", "W6"]
              }
            }
          ]
        },
        {
          "_id": "professional-dashboard-team-card",
          "_type": "core.card",
          "props": { "title": "Recent team activity", "description": "The latest visible changes across this workspace.", "tone": "success" },
          "children": [
            { "_id": "professional-dashboard-team-label", "_type": "core.section-label", "props": { "label": "Recently updated" } },
            { "_id": "professional-dashboard-team-1", "_type": "core.list-row", "props": { "primary": "Preventive maintenance", "secondary": "North facility · Updated 8 minutes ago", "trailing": "Ready", "initials": "PM", "tone": "success" } },
            { "_id": "professional-dashboard-team-2", "_type": "core.list-row", "props": { "primary": "Customer onboarding", "secondary": "West region · Updated 21 minutes ago", "trailing": "Review", "initials": "CO", "tone": "warning" } },
            { "_id": "professional-dashboard-team-3", "_type": "core.list-row", "props": { "primary": "Quarterly inspection", "secondary": "Central office · Updated 46 minutes ago", "trailing": "Open", "initials": "QI", "tone": "primary" } }
          ]
        }
      ]
    }
  ]
}
```

**Professional work queue - copy the complete page JSON**

```
{
  "blocks": [
    {
      "_id": "professional-queue-header",
      "_type": "core.page-header",
      "props": {
        "title": "Work queue",
        "lead": "A bounded, server-scoped table designed for fast triage instead of fetching an entire record graph.",
        "breadcrumb": ["Operations", "Work queue"]
      }
    },
    {
      "_id": "professional-queue-statuses",
      "_type": "core.container",
      "props": { "layout": "row" },
      "children": [
        { "_id": "professional-queue-status-all", "_type": "core.badge", "props": { "label": "All 128", "tone": "primary" } },
        { "_id": "professional-queue-status-progress", "_type": "core.badge", "props": { "label": "In progress 46", "tone": "success" } },
        { "_id": "professional-queue-status-risk", "_type": "core.badge", "props": { "label": "At risk 4", "tone": "warning" } },
        { "_id": "professional-queue-status-blocked", "_type": "core.badge", "props": { "label": "Blocked 3", "tone": "danger" } }
      ]
    },
    {
      "_id": "professional-queue-card",
      "_type": "core.card",
      "props": { "title": "Priority work", "description": "Preview rows; bind this block to an approved list operation for live tenant data.", "tone": "primary" },
      "children": [
        {
          "_id": "professional-queue-table",
          "_type": "core.data-table",
          "props": {
            "caption": "Priority work queue",
            "columns": [
              { "key": "reference", "label": "Reference", "align": "left" },
              { "key": "summary", "label": "Summary", "align": "left" },
              { "key": "owner", "label": "Owner", "align": "left" },
              { "key": "due", "label": "Due", "align": "left" },
              { "key": "status", "label": "Status", "align": "right" }
            ],
            "rows": [
              { "reference": "WO-1048", "summary": "Inspect cooling system", "owner": "Morgan Lee", "due": "Today", "status": "In progress" },
              { "reference": "TK-318", "summary": "Confirm access window", "owner": "Avery Patel", "due": "Today", "status": "Waiting" },
              { "reference": "WO-1051", "summary": "Replace safety signage", "owner": "Jordan Kim", "due": "Tomorrow", "status": "Ready" },
              { "reference": "AP-092", "summary": "Approve completion proof", "owner": "Riley Chen", "due": "Tomorrow", "status": "Review" }
            ]
          }
        }
      ]
    },
    {
      "_id": "professional-queue-empty",
      "_type": "core.empty-state",
      "props": {
        "title": "No work matches this view",
        "body": "Use this state when an approved query returns zero visible rows; do not substitute an unscoped fallback query."
      }
    }
  ]
}
```

**Professional record detail - copy the complete page JSON**

```
{
  "blocks": [
    {
      "_id": "professional-record-header",
      "_type": "core.page-header",
      "props": {
        "title": "WO-1048 · Inspect cooling system",
        "lead": "A composed record view that can sit beside Files, Conversations, Checklists, Workflow, and Record Activity.",
        "breadcrumb": ["Operations", "Work orders", "WO-1048"]
      }
    },
    {
      "_id": "professional-record-statuses",
      "_type": "core.container",
      "props": { "layout": "row" },
      "children": [
        { "_id": "professional-record-status", "_type": "core.badge", "props": { "label": "In progress", "tone": "success" } },
        { "_id": "professional-record-priority", "_type": "core.badge", "props": { "label": "High priority", "tone": "warning" } },
        { "_id": "professional-record-location", "_type": "core.badge", "props": { "label": "North facility", "tone": "neutral" } }
      ]
    },
    {
      "_id": "professional-record-grid",
      "_type": "core.container",
      "props": { "layout": "grid" },
      "children": [
        {
          "_id": "professional-record-summary",
          "_type": "core.card",
          "props": { "title": "Work summary", "description": "Use nested blocks to compose an editable page without bypassing the page contract.", "tone": "primary" },
          "children": [
            { "_id": "professional-record-summary-label", "_type": "core.section-label", "props": { "label": "Scope" } },
            { "_id": "professional-record-summary-text", "_type": "core.text", "props": { "text": "Inspect the rooftop cooling system, capture proof, and submit the completed checklist for approval.", "variant": "body", "align": "left" } },
            { "_id": "professional-record-owner", "_type": "core.list-row", "props": { "primary": "Morgan Lee", "secondary": "Assigned technician", "trailing": "Today", "initials": "ML", "tone": "primary" } }
          ]
        },
        {
          "_id": "professional-record-proof",
          "_type": "core.card",
          "props": { "title": "Completion proof", "description": "Files and photos remain secured native records; the presentation block only explains the state.", "tone": "success" },
          "children": [
            { "_id": "professional-record-proof-empty", "_type": "core.empty-state", "props": { "title": "No proof attached yet", "body": "Attach photos or documents to checklist items before submitting this work for approval." } }
          ]
        }
      ]
    }
  ]
}
```

**Flexible control-panel showcase - copy the complete page JSON**

```
{
  "blocks": [
    {
      "_id": "control-panel-header",
      "_type": "core.page-header",
      "props": {
        "title": "Service command center",
        "lead": "An original BuildWithHQ composition showing live-looking operational rhythm without prescribing one dashboard layout.",
        "breadcrumb": ["Operations", "Today"]
      }
    },
    {
      "_id": "control-panel-kpis",
      "_type": "core.container",
      "props": { "layout": "grid", "gridMode": "twelve-column", "gap": "normal" },
      "children": [
        {
          "_id": "control-panel-kpi-open",
          "_type": "core.stat-tile",
          "props": {
            "label": "Open requests", "value": "248", "delta": "18 since Monday", "direction": "up", "tone": "primary", "iconName": "inbox",
            "responsive": { "desktop": { "span": 3 }, "tablet": { "span": 6 }, "mobile": { "span": 12 } }
          }
        },
        {
          "_id": "control-panel-kpi-response",
          "_type": "core.stat-tile",
          "props": {
            "label": "First response", "value": "8m", "delta": "2m faster", "direction": "up", "tone": "success", "iconName": "clock",
            "responsive": { "desktop": { "span": 3 }, "tablet": { "span": 6 }, "mobile": { "span": 12 } }
          }
        },
        {
          "_id": "control-panel-kpi-completed",
          "_type": "core.stat-tile",
          "props": {
            "label": "Completed today", "value": "73", "delta": "11 above pace", "direction": "up", "tone": "success", "iconName": "check-circle",
            "responsive": { "desktop": { "span": 3 }, "tablet": { "span": 6 }, "mobile": { "span": 12 } }
          }
        },
        {
          "_id": "control-panel-kpi-risk",
          "_type": "core.stat-tile",
          "props": {
            "label": "Needs attention", "value": "12", "delta": "3 due this hour", "direction": "down", "tone": "warning", "iconName": "activity",
            "responsive": { "desktop": { "span": 3 }, "tablet": { "span": 6 }, "mobile": { "span": 12 } }
          }
        }
      ]
    },
    {
      "_id": "control-panel-primary-grid",
      "_type": "core.container",
      "props": { "layout": "grid", "gridMode": "twelve-column", "gap": "relaxed" },
      "children": [
        {
          "_id": "control-panel-demand-card",
          "_type": "core.card",
          "props": {
            "title": "Demand and completion",
            "description": "A seven-day view. Replace the preview document with one approved server-scoped binding.",
            "tone": "primary",
            "responsive": { "desktop": { "span": 8 }, "tablet": { "span": 12 }, "mobile": { "span": 12 } }
          },
          "children": [
            {
              "_id": "control-panel-demand-chart",
              "_type": "core.series-chart",
              "props": {
                "title": "Requests compared with completions",
                "variant": "line",
                "defaultPeriodKey": "week",
                "periods": [
                  {
                    "key": "week",
                    "label": "7 days",
                    "labels": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
                    "series": [
                      { "key": "opened", "label": "Opened", "tone": "primary", "values": [32, 41, 36, 54, 49, 28, 24] },
                      { "key": "completed", "label": "Completed", "tone": "success", "values": [27, 35, 39, 45, 51, 34, 31] }
                    ]
                  },
                  {
                    "key": "month",
                    "label": "4 weeks",
                    "labels": ["Week 1", "Week 2", "Week 3", "Week 4"],
                    "series": [
                      { "key": "opened", "label": "Opened", "tone": "primary", "values": [228, 241, 219, 264] },
                      { "key": "completed", "label": "Completed", "tone": "success", "values": [215, 232, 238, 251] }
                    ]
                  }
                ]
              }
            }
          ]
        },
        {
          "_id": "control-panel-team-card",
          "_type": "core.card",
          "props": {
            "title": "Team pulse", "description": "Recent visible ownership and status.", "tone": "success",
            "responsive": { "desktop": { "span": 4 }, "tablet": { "span": 12 }, "mobile": { "span": 12 } }
          },
          "children": [
            {
              "_id": "control-panel-team-list",
              "_type": "core.entity-list",
              "props": {
                "title": "Active teammates",
                "items": [
                  { "id": "team-avery", "primary": "Avery Chen", "secondary": "Onboarding queue", "initials": "AC", "status": { "key": "available", "label": "Available", "tone": "success" }, "trailing": "12", "trailingLabel": "open" },
                  { "id": "team-morgan", "primary": "Morgan Lee", "secondary": "Field service", "initials": "ML", "status": { "key": "focused", "label": "Focused", "tone": "primary" }, "trailing": "8", "trailingLabel": "open" },
                  { "id": "team-jordan", "primary": "Jordan Patel", "secondary": "Escalations", "initials": "JP", "status": { "key": "busy", "label": "Busy", "tone": "warning" }, "trailing": "5", "trailingLabel": "open" },
                  { "id": "team-riley", "primary": "Riley Brooks", "secondary": "Knowledge review", "initials": "RB", "status": { "key": "available", "label": "Available", "tone": "success" }, "trailing": "9", "trailingLabel": "open" }
                ]
              }
            }
          ]
        }
      ]
    },
    {
      "_id": "control-panel-secondary-grid",
      "_type": "core.container",
      "props": { "layout": "grid", "gridMode": "twelve-column", "gap": "normal" },
      "children": [
        {
          "_id": "control-panel-priority-card",
          "_type": "core.card",
          "props": {
            "title": "Priority mix", "description": "Distribution of the current authorized workload.", "tone": "warning",
            "responsive": { "desktop": { "span": 5 }, "tablet": { "span": 6 }, "mobile": { "span": 12 } }
          },
          "children": [
            {
              "_id": "control-panel-priority-list",
              "_type": "core.progress-list",
              "props": {
                "items": [
                  { "key": "urgent", "label": "Urgent", "value": 12, "maximum": 248, "displayValue": "12", "tone": "danger" },
                  { "key": "high", "label": "High", "value": 54, "maximum": 248, "displayValue": "54", "tone": "warning" },
                  { "key": "normal", "label": "Normal", "value": 146, "maximum": 248, "displayValue": "146", "tone": "primary" },
                  { "key": "low", "label": "Low", "value": 36, "maximum": 248, "displayValue": "36", "tone": "neutral" }
                ]
              }
            }
          ]
        },
        {
          "_id": "control-panel-activity-card",
          "_type": "core.card",
          "props": {
            "title": "Recent activity", "description": "Changes already authorized for this user.", "tone": "primary",
            "responsive": { "desktop": { "span": 7 }, "tablet": { "span": 6 }, "mobile": { "span": 12 } }
          },
          "children": [
            {
              "_id": "control-panel-activity-timeline",
              "_type": "core.timeline",
              "props": {
                "items": [
                  { "id": "event-1", "occurredUtc": "2026-09-05T15:42:00Z", "title": "Ticket BH-1842 resolved", "description": "Proof reviewed and customer notified.", "actor": "Avery Chen", "tone": "success" },
                  { "id": "event-2", "occurredUtc": "2026-09-05T15:31:00Z", "title": "Work order WO-882 assigned", "description": "Assigned to the west field team.", "actor": "Morgan Lee", "tone": "primary" },
                  { "id": "event-3", "occurredUtc": "2026-09-05T15:08:00Z", "title": "Checklist submitted", "description": "Site opening checklist is ready for signoff.", "actor": "Riley Brooks", "tone": "warning" }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}
```

**Live checklist and Contacts actions - copy the complete page JSON**

```
{
  "blocks": [
    {
      "_id": "live-actions-header",
      "_type": "core.page-header",
      "props": {
        "title": "Live checklist and contact actions",
        "lead": "These components receive only the records and actions authorized for the signed-in user. Checklist toggles use optimistic concurrency; contact actions refetch their scoped presentation after each write."
      }
    },
    {
      "_id": "live-actions-layout",
      "_type": "core.container",
      "props": {
        "layout": "grid",
        "gridMode": "twelve-column",
        "gap": "normal"
      },
      "children": [
        {
          "_id": "live-actions-checklist-card",
          "_type": "core.card",
          "props": {
            "title": "Checklist work",
            "description": "Items outside the user's DataRole and Location scope are never sent to the browser.",
            "responsive": {
              "desktop": { "span": 5 },
              "tablet": { "span": 12 },
              "mobile": { "span": 12 }
            }
          },
          "children": [
            {
              "_id": "live-actions-checklist",
              "_type": "core.task-list",
              "bindingKey": "checklists-signoffs.presentation",
              "dataKey": "tasks",
              "props": {}
            }
          ]
        },
        {
          "_id": "live-actions-contacts-card",
          "_type": "core.card",
          "props": {
            "title": "Recent contacts",
            "description": "The grid is bounded to 25 visible contacts and each row declares only its currently valid favorite action.",
            "responsive": {
              "desktop": { "span": 7 },
              "tablet": { "span": 12 },
              "mobile": { "span": 12 }
            }
          },
          "children": [
            {
              "_id": "live-actions-contacts",
              "_type": "core.presentation-grid",
              "bindingKey": "contacts.presentation",
              "dataKey": "table",
              "props": {}
            }
          ]
        }
      ]
    }
  ]
}
```

**Work Order Home panel - copy the complete page JSON**

```
{
  "blocks": [
    {
      "_id": "home-work-orders-presentation",
      "_type": "core.card",
      "props": {
        "title": "Work order overview",
        "description": "Current workload, status, trends and activity from one server-scoped API presentation.",
        "tone": "neutral"
      },
      "children": [
        {
          "_id": "home-work-orders-metrics",
          "_type": "core.metric-strip",
          "bindingKey": "work-orders.presentation",
          "dataKey": "metrics",
          "props": {}
        },
        {
          "_id": "home-work-orders-summary",
          "_type": "core.container",
          "props": {
            "layout": "grid"
          },
          "children": [
            {
              "_id": "home-work-orders-status",
              "_type": "core.progress-list",
              "bindingKey": "work-orders.presentation",
              "dataKey": "byStatus",
              "props": {}
            },
            {
              "_id": "home-work-orders-recent",
              "_type": "core.entity-list",
              "bindingKey": "work-orders.presentation",
              "dataKey": "recent",
              "props": {}
            }
          ]
        },
        {
          "_id": "home-work-orders-trend",
          "_type": "core.series-chart",
          "bindingKey": "work-orders.presentation",
          "dataKey": "trend",
          "props": {}
        },
        {
          "_id": "home-work-orders-table",
          "_type": "core.presentation-grid",
          "bindingKey": "work-orders.presentation",
          "dataKey": "table",
          "props": {}
        },
        {
          "_id": "home-work-orders-timeline",
          "_type": "core.timeline",
          "bindingKey": "work-orders.presentation",
          "dataKey": "timeline",
          "props": {}
        }
      ]
    }
  ]
}
```

**Work Order command center - copy the complete page JSON**

```
{
  "blocks": [
    {
      "_id": "work-order-command-center-header",
      "_type": "core.page-header",
      "props": {
        "title": "Work order command center",
        "lead": "Live workload, status, trends and recent activity from one server-scoped API presentation.",
        "breadcrumb": ["Operations", "Work orders"]
      }
    },
    {
      "_id": "work-order-command-center-metrics",
      "_type": "core.metric-strip",
      "bindingKey": "work-orders.presentation",
      "dataKey": "metrics",
      "props": {}
    },
    {
      "_id": "work-order-command-center-summary",
      "_type": "core.container",
      "props": {
        "layout": "grid"
      },
      "children": [
        {
          "_id": "work-order-command-center-status",
          "_type": "core.progress-list",
          "bindingKey": "work-orders.presentation",
          "dataKey": "byStatus",
          "props": {}
        },
        {
          "_id": "work-order-command-center-recent",
          "_type": "core.entity-list",
          "bindingKey": "work-orders.presentation",
          "dataKey": "recent",
          "props": {}
        }
      ]
    },
    {
      "_id": "work-order-command-center-trend",
      "_type": "core.series-chart",
      "bindingKey": "work-orders.presentation",
      "dataKey": "trend",
      "props": {}
    },
    {
      "_id": "work-order-command-center-table",
      "_type": "core.presentation-grid",
      "bindingKey": "work-orders.presentation",
      "dataKey": "table",
      "props": {}
    },
    {
      "_id": "work-order-command-center-timeline",
      "_type": "core.timeline",
      "bindingKey": "work-orders.presentation",
      "dataKey": "timeline",
      "props": {}
    }
  ]
}
```

Tip

Keep every _id stable while editing. Template upgrades use block identity to compare and merge changes. Give a copied block a new unique ID instead of duplicating an existing one.

## 4. Edit the pages in Puck

1. Open an account-owned workshop SaaS and create or open a page in Design mode.
2. Drag a component from **BuildWithHQ components**, or load one of the complete page sources above through the supported page authoring flow.
3. Select a Container and choose its Layout, Grid behavior and Spacing. For any block inside a 12-column canvas, choose Desktop, Tablet and Mobile width through `desktopSpan`, `tabletSpan` and `mobileSpan`. Advanced JSON remains available, but routine layout work does not require it.
4. Preview desktop and mobile layouts, save a draft, then publish through the normal page validator.

For example, this is the complete properties object for a stat tile:

```
{
  "label": "Open work",
  "value": "128",
  "delta": "12 this week",
  "direction": "up",
  "iconName": "inbox",
  "tone": "primary"
}
```

The editor round-trips these properties into `block.props`. It preserves canonical block identity, parent/child structure, responsive settings, event bindings, security metadata, `bindingKey` and `dataKey`.

## 5. Choose a token-safe theme

The presets use the existing SaaS app theme contract: `themeJson` selects `light`, `dark` or `system`; `cssVariables` contains allowlisted runtime tokens; and `designTokensJson` sets base spacing and radius. The runtime parses the document fail-closed, stamps the document element, and applies the tokens to painted components.

**BuildWithHQ Indigo Light - copy the complete theme JSON**

```
{
  "schemaVersion": 1,
  "themeKey": "buildwithhq-indigo-light",
  "themeJson": { "schemaVersion": 1, "name": "BuildWithHQ Indigo Light", "mode": "light" },
  "cssVariables": {
    "--runtime-primary": "#4b45e8",
    "--runtime-primary-strong": "#302b8e",
    "--runtime-primary-tint": "rgba(75,69,232,.13)",
    "--runtime-page": "#f4f6fb",
    "--runtime-surface": "#ffffff",
    "--runtime-surface-raised": "#f8f9fc",
    "--runtime-ink": "#17202f",
    "--runtime-ink-muted": "#667085",
    "--runtime-line": "#dfe3ed"
  },
  "designTokensJson": { "spacingBase": 8, "radiusBase": 8 }
}
```

**Executive Slate Dark - copy the complete theme JSON**

```
{
  "schemaVersion": 1,
  "themeKey": "executive-slate-dark",
  "themeJson": { "schemaVersion": 1, "name": "Executive Slate Dark", "mode": "dark" },
  "cssVariables": {
    "--runtime-primary": "#9ea8ff",
    "--runtime-primary-strong": "#c7ccff",
    "--runtime-primary-tint": "rgba(158,168,255,.18)",
    "--runtime-page": "#0e1420",
    "--runtime-surface": "#171e2c",
    "--runtime-surface-raised": "#20293a",
    "--runtime-ink": "#edf1f7",
    "--runtime-ink-muted": "#a8b2c4",
    "--runtime-line": "#303b50"
  },
  "designTokensJson": { "spacingBase": 8, "radiusBase": 10 }
}
```

**Service Emerald Light - copy the complete theme JSON**

```
{
  "schemaVersion": 1,
  "themeKey": "service-emerald-light",
  "themeJson": { "schemaVersion": 1, "name": "Service Emerald Light", "mode": "light" },
  "cssVariables": {
    "--runtime-primary": "#16705a",
    "--runtime-primary-strong": "#0d4f40",
    "--runtime-primary-tint": "rgba(22,112,90,.14)",
    "--runtime-page": "#f2f7f5",
    "--runtime-surface": "#ffffff",
    "--runtime-surface-raised": "#f6faf8",
    "--runtime-ink": "#172521",
    "--runtime-ink-muted": "#61716b",
    "--runtime-line": "#d7e5df"
  },
  "designTokensJson": { "spacingBase": 8, "radiusBase": 8 }
}
```

Important

Do not paste theme JSON into a tenant table or add an arbitrary CSS/script field. Theme writes must go through the supported version-fenced builder contract. Template-pack artifact schema v2 pins pages and effective components, not the optional legacy live ThemeKey lookup; these presets are instead versioned by the developer-kit integrity manifest and ZIP SHA-256. The public builder theme switcher is still a separate delivery step.

## 6. Replace preview values with live, scoped data

Static values are useful while designing. For live data, register a reviewed binding and put only its stable key on the block. `dataKey` may select a bounded property from the returned JSON; it is not a query language.

```
{
  "_id": "visible-work-table",
  "_type": "core.data-table",
  "bindingKey": "work-orders.current-page",
  "dataKey": "items",
  "props": {
    "caption": "Visible work orders",
    "columns": [
      { "key": "reference", "label": "Reference", "align": "left" },
      { "key": "summary", "label": "Summary", "align": "left" },
      { "key": "status", "label": "Status", "align": "right" }
    ]
  }
}
```

The approved server operation may return shapes like these:

```
{
  "stat": { "value": 128, "delta": "12 this week", "direction": "up" },
  "chart": {
    "title": "Completed work",
    "series": [38, 45, 42, 56, 61, 73],
    "labels": ["W1", "W2", "W3", "W4", "W5", "W6"]
  },
  "table": {
    "items": [
      { "reference": "WO-1048", "summary": "Inspect cooling system", "status": "In progress" }
    ]
  }
}
```

- A stat accepts a scalar or an object with `value`, `delta` and `direction`.
- A chart accepts finite numeric `series` plus short labels.
- A table accepts an array or an object containing `items`; columns explicitly select display fields.
- A failed bound table never falls back to its static preview rows. It shows a loading, error or no-visible-data state.

Important

Page JSON must never contain a database name, connection string, SaaSAppId, AppAccountId, UserId, DataRoleId or LocationId as authorization evidence. The server derives identity and scope from the verified session.

## 7. Turn the workshop pages into a reusable template

1. Customize the pages in an account-owned workshop SaaS.
2. Save the selected theme through the supported version-fenced authoring contract when that builder surface is available.
3. Harvest each owned Page with `POST /api/apps/{saasAppId}/template-harvests`.
4. Attach the harvested artifacts to a draft pack and run the existing pack validator.
5. Publish an immutable Template Library version.
6. Install that exact version into a different disposable SaaS and run real auth, permission, binding, layout and failure tests before offering it broadly.

**Copy the source-kit manifest**

```
{
  "schemaVersion": 1,
  "templateKey": "professional-foundation",
  "templateName": "BuildWithHQ Professional Foundation",
  "version": "1.0.0",
  "description": "Clean-room professional page compositions and theme presets built from the canonical BuildWithHQ component registry.",
  "delivery": "authoring-source-for-exact-version-template-pack",
  "installRequiresExactVersion": true,
  "runtimeDataAccess": "approved-server-scoped-bindings-only",
  "publicDistribution": {
    "kind": "builder-developer-kit",
    "version": "1.20.70",
    "supportedProducts": [
      "buildwithhq",
      "api43"
    ],
    "apiBaseUrl": "https://api.buildwithhq.com",
    "mcpEndpointTemplate": "https://api.buildwithhq.com/v1/apps/{saasAppId}/mcp",
    "archiveName": "BuildWithHQ-API43-Developer-Kit-1.20.70.zip"
  },
  "requiredComponents": [
    "module.support-lanes",
    "module.support-lanes.toolbar",
    "module.support-lanes.list",
    "module.support-lanes.editor",
    "core.badge",
    "core.card",
    "core.chart",
    "core.container",
    "core.data-table",
    "core.empty-state",
    "core.list-row",
    "core.page-header",
    "core.section-label",
    "core.stat-tile",
    "core.text"
  ],
  "pages": [
    {
      "pageKey": "ProfessionalDashboard",
      "name": "Professional dashboard",
      "path": "pages/professional-dashboard.json"
    },
    {
      "pageKey": "ProfessionalQueue",
      "name": "Professional work queue",
      "path": "pages/professional-queue.json"
    },
    {
      "pageKey": "ProfessionalRecord",
      "name": "Professional record detail",
      "path": "pages/professional-record.json"
    }
  ],
  "themes": [
    {
      "themeKey": "buildwithhq-indigo-light",
      "name": "BuildWithHQ Indigo Light",
      "path": "themes/buildwithhq-indigo-light.json"
    },
    {
      "themeKey": "executive-slate-dark",
      "name": "Executive Slate Dark",
      "path": "themes/executive-slate-dark.json"
    },
    {
      "themeKey": "service-emerald-light",
      "name": "Service Emerald Light",
      "path": "themes/service-emerald-light.json"
    }
  ],
  "publication": {
    "harvestEndpoint": "POST /api/apps/{saasAppId}/template-harvests",
    "artifactTypes": [
      "Page"
    ],
    "ownership": "verified-account-owner",
    "destination": "BuildWithHQ_TemplateLibrary",
    "snapshot": "published-immutable-exact-version",
    "exactVersionContents": [
      "PackSettings",
      "Page",
      "Component"
    ],
    "themePresetDelivery": "checksummed-developer-kit-and-version-fenced-builder-theme-write"
  },
  "security": {
    "identitySource": "verified-server-session",
    "pageJsonCarriesAuthority": false,
    "dataBindings": "tenant+datarole+location scoped before serialization"
  }
}
```

Template installation is snapshot isolation. A later upstream page or component edit can become a new pack version, but it must not silently mutate a tenant that installed an earlier one. Apply a preset theme separately through the version-fenced theme write; do not claim a live theme catalog lookup is part of the immutable pack.

## 8. Know the fail-closed limits and verify your template

- Tables render at most 500 rows and 24 declared columns. Keep pagination and filtering on the server.
- Task lists render at most 1,000 rows; grids declare at most eight actions and eight action keys per row.
- Charts render at most 60 finite points. Use a summarized binding rather than sending raw event history.
- `dataKey` is at most eight safe path segments. Missing or invalid paths return no selected data.
- Text, labels, breadcrumbs and cell values are length-bounded and rendered as React text, not executable HTML.
- No CDN, arbitrary runtime script, direct SQL connection or physical tenant database selector is introduced.

**Repository maintainers** run the source, renderer, editor and catalog checks below before releasing a new foundation version. Builders installing an approved exact version do not need these commands:

```
python -m pytest templates\professional-foundation\tests -q
npm --prefix apps\tenant-runtime test -- src\ProfessionalPrimitives.test.tsx src\PageRenderer.test.tsx src\PuckPageDesignerAdapter.test.ts
npm --prefix apps\tenant-runtime run build

# Regenerate the implementation catalog while retaining runtime observations.
python catalog-generator\generate_catalog.py --observations artifacts\catalog-observations\tenant-runtime-2026-09-03.jsonl
python catalog-generator\generate_catalog.py --check
```

Then run an authenticated browser journey through the real auth, SQL, API and runtime paths. Check the selected theme, all expected blocks, empty/loading/error states, mobile overflow, keyboard access, cross-tenant rejection and exact result cardinality.

Continue with the [interactive API presentation guide](interactive-api-presentations.html), [complete React component catalog](react-component-catalog.html), [page authoring guide](page-editor.html), and [template versioning guide](templates-forking.html).

## Support lane manager

The editable organization-owned email/SMS lane manager is included in the current kit. See [support lanes, installation and API contracts](../api/support-lanes.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/professional-template-foundation.html).

---
title: "Support for React"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/support-for-react.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Support for React

Use Tailwind, ordinary CSS, CSS Modules, inline styles, component libraries, or CSS-in-JS with your React frontend.

## In brief

- **Audience:** Builders and React developers
- **Hosted pages:** Registered components and validated CSS
- **Custom frontend:** Your React build

BuildWithHQ uses React for its tenant frontend. You can style a developer-owned React application with any of the approaches below while continuing to use the secured Developer API. Styling does not change authentication, scopes, record permissions, or concurrency rules.

## First choose where your React code runs

- **Hosted SaaS pages:** compose registered components in the page editor and use the app theme and App Assets → Custom CSS for supported overrides. Page JSON is configuration, not an arbitrary JavaScript, JSX, or npm execution environment.
- **Your own React frontend:** install compatible dependencies in your project, build your application, and deploy its compiled output. You control its styling pipeline, providers, routing, and security headers.
- **A new hosted renderer component:** adding a package or component requires reviewed source integration, component registration, testing, and a runtime deployment. Uploading a file does not register a React component.

The examples are small source-code illustrations, not executable page JSON. Third-party package compatibility must be verified in your actual project; this page does not claim those packages are preinstalled or certified in the hosted runtime.

A developer-owned frontend needs its own deployment. The hosted page editor and App Assets do not install a compiled custom React application. A portable hosted custom-React installation workflow is not currently available; use registered hosted components or deploy your frontend separately against the supported APIs.

## 1. React with Tailwind

Use utility classes in JSX, with Tailwind configured in your React build. Compile the CSS before deployment. The current hosted runtime uses a TailAdmin-derived visual system; that does not mean it runs a Tailwind compiler on uploaded text.

```
export function Panel() {
  return <section className="rounded-xl border border-slate-200 bg-white p-6">
    <h2 className="text-xl font-semibold text-slate-900">Customers</h2>
  </section>;
}
```

Ensure Tailwind scans all relevant component sources. Classes generated only in database page JSON may be absent from the build; include them using your Tailwind version's supported source configuration. Avoid constructing incomplete class strings such as `bg-${color}-500`; map choices to complete class names. See [Tailwind's source-detection guide](https://tailwindcss.com/docs/detecting-classes-in-source-files).

For hosted pages, publish the resulting CSS through the validated stylesheet workflow and use class properties supported by the selected component. A CSS file cannot add missing JSX or behavior. Check framework resets against existing shell and form styles.

## 2. React with ordinary CSS files

Import a CSS file into your own React bundle, or load a stylesheet in the host document. Prefix app-specific selectors to avoid changing unrelated pages. React uses `className` for CSS classes; see [React's styling introduction](https://react.dev/learn#adding-styles).

```
// CustomerPanel.jsx
import './customer-panel.css';
export function CustomerPanel() {
  return <section className="acme-customer-panel">Customers</section>;
}

/* customer-panel.css — a separate file */
.acme-customer-panel {
  padding: 1.5rem;
  border: 1px solid #e2e8f0;
  border-radius: 0.75rem;
}
```

For an existing hosted SaaS, use **Assets → Custom CSS → Preview CSS → Publish CSS**. Paste CSS only, without style tags or script. Upload design files explicitly as public only when they need unauthenticated delivery, and use the returned app-scoped asset URLs. See [SaaS CSS and design assets](saas-css-and-design-assets.html)  for validation and URL rules.

## 3. React with CSS Modules

CSS Modules give imported class names a build-generated scope. In a Vite project, use a `.module.css` file and import its class mapping. See [Vite's CSS Modules documentation](https://vite.dev/guide/features.html#css-modules).

```
// CustomerPanel.jsx
import styles from './CustomerPanel.module.css';
export function CustomerPanel() {
  return <section className={styles.panel}>Customers</section>;
}

/* CustomerPanel.module.css — a separate file */
.panel { padding: 1.5rem; border-radius: 0.75rem; }
```

Deploy the compiled JavaScript and CSS together. Pasting `.panel` into the hosted CSS editor does not create the generated class mapping. Modules isolate class names, but inherited styles and global rules can still affect a component.

## 4. React with inline styles

Use React's `style` object for values calculated at render time. Property names use camelCase. Inline style objects are not a replacement for stylesheet media queries, hover/focus selectors, or a consistent design system.

```
export function Progress({ percent }) {
  const width = Math.max(0, Math.min(100, percent));
  return <div role="progressbar" aria-valuemin={0} aria-valuemax={100}
    aria-valuenow={width} aria-label="Progress"
    style={{ width: `${width}%`, minHeight: 8, backgroundColor: '#465fff' }} />;
}
```

This works in React source; a hosted page block accepts only its registered styling properties. Check your host's Content Security Policy (CSP), since some policies restrict inline styles. Do not weaken security headers just to make a styling example work.

## 5. React with component libraries

You can integrate a React component library in your own frontend, subject to its React version, license, accessibility, and build requirements. Follow the library's installation instructions, add required theme providers once near the application root, and import its required styles. A UI library does not provide BuildWithHQ authorization or automatically connect its controls to API routes.

Use one primary visual system. Check dialogs and dropdown portals, stacking order, keyboard navigation, mobile layouts, dark mode, and CSS reset collisions. Keep CRUD actions wired to the documented secured clients, including validation and stale-write handling. Hosted runtime integration still requires registered components and a reviewed build.

## 6. React with styled-components or similar CSS-in-JS tools

Install the chosen package in your own React project and include it in the production build. For example, with styled-components installed:

```
import styled from 'styled-components';

const Panel = styled.section`
  padding: 1.5rem;
  border: 1px solid #e2e8f0;
  border-radius: 0.75rem;
`;

export function CustomerPanel() {
  return <Panel>Customers</Panel>;
}
```

See the [styled-components basics](https://styled-components.com/docs/basics). Emotion and other tools have their own setup. Runtime style injection must satisfy the host's CSP; server-rendered apps also need the library's supported style extraction and hydration setup. Do not interpolate untrusted user CSS. The hosted CSS editor accepts CSS, not tagged-template JavaScript or package imports.

## Before publishing

1. Choose the host and styling approach. For existing hosted pages, start with theme settings and validated CSS overrides.
2. Build and test using your project's scripts; do not use a development server as the public production server.
3. Check desktop and mobile, keyboard focus, contrast, loading, empty, validation, permission-denied, and stale-write states.
4. Verify CSS, fonts, images, and lazy-loaded chunks load under the deployed security policy. Keep privileged app credentials on the backend, never in CSS or browser bundles.
5. Publish through the relevant page/asset or frontend deployment workflow, then retest the served application.

Continue with [TailAdmin template design and React customization](tailadmin-template-design-and-react-customization.html), [the headless application guide](headless-application-kit.html), or [the React component catalog](react-component-catalog.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/support-for-react.html).

---
title: "Apply a TailAdmin-style design and customize every React page"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/tailadmin-template-design-and-react-customization.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Apply a TailAdmin-style design and customize every React page

Set up an owned CSS and token system from a licensed React template, refine shared components, edit each SaaS page in Puck, and publish the finished design safely.

## In brief

- **Visual reference:** TailAdmin-style
- **Page editor:** Puck
- **Shared styling:** Owned React + CSS
- **Authority:** Server enforced

A premium React template such as TailAdmin can provide the visual language for a BuildWithHQ SaaS: spacing, cards, tables, forms, navigation, badges, charts and responsive layouts. BuildWithHQ remains the application runtime. Adapt the design into the owned component and token system; do not replace authentication, routing, data bindings, secured module APIs or canonical page JSON.

[Prepare the design source](#prepare) [Set up CSS](#css) [Customize React](#react) [Edit every page](#pages) [Verify and publish](#verify)

Note

If you are only customizing an installed template through the Builder, begin at “Edit each page in Design mode.” Repository-level CSS and React changes are for the template maintainer who is creating the reusable foundation.

## 1. Prepare an owned design source

1. Choose a React/admin design whose license permits your intended use. Record its version, source, license and any required notice.
2. Keep the unmodified vendor snapshot as review evidence. Do not make it the production runtime.
3. Create an owned BuildWithHQ adaptation. For the current TailAdmin-derived system, use `templates/tailadmin-battle-system/`; its README records the reviewed TailAdmin 2.3.0 source and `LICENSE.tailadmin.md` carries the MIT notice.
4. Inventory useful patterns—shell, page header, cards, tables, fields, dialogs, status badges, charts, empty states and mobile navigation—and map each to an existing BuildWithHQ primitive or native module.
5. Do not import the template's router, login, mock API, data store or example business logic.

Important

Never load a CSS framework from a CDN or paste scripts, arbitrary HTML, secrets, database names or executable event strings into page JSON. Repository-maintained foundations use bundled React and compiled CSS; an individual SaaS may also publish validated app-scoped CSS through App Assets.

## 2. Work in a guarded workshop SaaS

1. Create or select an account-owned workshop SaaS—not a customer tenant.
2. Install the current Professional Foundation or the guarded TailAdmin battle manifest.
3. Confirm that the expected first-class pages and registered components resolve before changing their appearance.
4. Capture the starting desktop and mobile screens so visual changes can be compared rather than judged from memory.
5. Keep all lifecycle behavior in the existing native modules. The workshop is for design and template authoring, not direct database editing.

## 3. Confirm the shared CSS entry points

The tenant runtime already loads the shared professional primitives first and the app-level stylesheet second:

```
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";
import "@buildwithhq/ui/professional.css";
import "./styles.css";
```

This order is intentional. `@buildwithhq/ui/professional.css` supplies safe reusable component styling. `apps/tenant-runtime/src/styles.css` owns the shell, theme defaults and product-level refinements and may deliberately override shared rules.

Do not paste all of TailAdmin's generated CSS into `styles.css`. Translate the selected pattern into small owned classes and existing `--runtime-*` tokens. This keeps the bundle understandable and prevents unrelated template selectors from changing Puck, native modules or dialogs.

### App-scoped CSS and design assets

For one SaaS, open **App Assets**. The **Custom CSS** window accepts UTF-8 CSS, previews it locally, and publishes it as that app's public `theme.css`. Use this for brand tokens and bounded app overrides; use the repository CSS entry points above when creating or changing the shared reusable foundation.

1. Enter an optional virtual **Asset upload folder**, such as `brand/images`. This organizes metadata only; it cannot select a server or operating-system directory.
2. Assets are private by default. Select **Public design asset** only for a logo, image, font, video, PDF, or file that a rendered template must request without an authenticated download call.
3. Upload the file, then use the returned immutable URL: `https://assets.buildwithhq.com/{saasAppId}/{assetId}`.
4. Reference that URL from a registered component property, an image/logo field, or a stylesheet `url(...)`. Published CSS may reference only relative paths, fragments, or the same SaaS app's asset prefix.
5. Use **Preview CSS**, review desktop and mobile pages, then choose **Publish CSS**. The runtime activates the latest public stylesheet for the signed-in app.

Note

The appliance operator sets the physical upload root with BWHQ_FILE_STORAGE_ROOT and routes DNS/TLS for assets.buildwithhq.com. Builders never receive a filesystem path or database permission.

Important

Uploads accept all extensions except.dll,.com and.exe. That is an upload rule, not an inline-execution rule: only validated CSS and passive image, video, font and PDF types render inline. HTML, SVG, scripts, archives and unknown types are downloaded as inert attachments with nosniff and a sandbox policy.

## 4. Establish the theme before styling individual pages

Choose one light, dark or system direction and set the allowlisted theme variables through the supported version-fenced theme contract. A starting light theme looks like this:

```
{
  "schemaVersion": 1,
  "themeKey": "my-saas-light",
  "themeJson": { "schemaVersion": 1, "name": "My SaaS Light", "mode": "light" },
  "cssVariables": {
    "--runtime-primary": "#465fff",
    "--runtime-primary-strong": "#3641f5",
    "--runtime-primary-tint": "#ecf3ff",
    "--runtime-page": "#f9fafb",
    "--runtime-surface": "#ffffff",
    "--runtime-ink": "#101828",
    "--runtime-ink-muted": "#667085",
    "--runtime-line": "#e4e7ec"
  },
  "designTokensJson": { "spacingBase": 8, "radiusBase": 8 }
}
```

Use tokens for page/surface colors, ink, muted ink, boundaries, primary and semantic tones. The runtime also supplies the shared spacing, font-size, radius and shadow vocabulary. Change the theme when a value represents the SaaS brand; change component CSS when it represents component structure.

Important

Do not insert theme rows directly into a tenant database and do not add arbitrary CSS or script fields to the theme document. Save through the supported theme API so expected-version checks and validation remain active.

## 5. Polish shared primitives once

Before customizing twenty pages independently, finish one shared treatment for each repeated element:

- shell content width, gutters, sidebar, top bar, selected navigation and mobile menu;
- page headers, breadcrumbs and action alignment;
- primary, secondary, quiet, danger and icon-only buttons;
- fields, labels, help text, validation, disabled controls and focus rings;
- cards, metrics, tables, tabs, badges, dropdowns, dialogs and confirmations;
- loading, empty, permission-denied, stale-write, error and success states;
- the shared 25×25 gray/gold favorite star and its accessible label/focus state.

Shared React primitives live in `packages/ui/src/professional-primitives.tsx`; their styles live in `packages/ui/src/professional-primitives.css`; the bounded icon vocabulary lives in `packages/ui/src/icon-registry.tsx`. Improve these when every module should receive the same treatment.

## 6. Customize the React look and behavior at the correct layer

| Desired change | Correct owner |
| --- | --- |
| Brand color, page background, shared ink or border color | SaaS theme tokens |
| All cards/tables/metrics need the same refinement | `packages/ui` shared primitive and CSS |
| Shell, sidebar, top bar, dialog or application-wide state | `apps/tenant-runtime/src/styles.css` and the owning shell component |
| Only Calendar, Mail, Contacts or another native module needs a special interaction | That module's `apps/tenant-runtime/src/*Module.tsx` and focused CSS/tests |
| Page order, columns, responsive spans or registered component properties | Puck/canonical page JSON |
| A new reusable visual block | Reviewed React component, static renderer registration, Puck property schema and tests |
| A new data mutation | Typed client, authorized route/service and reviewed stored procedure before any control is shown |

Keep renderer registration static. Component metadata must never become an arbitrary import path. Expose only intentional, validated Puck properties, and render server-returned text as React content rather than executable markup.

### When adapting a TailAdmin component

1. Remove demo data, routing, authentication and network calls.
2. Replace hard-coded colors, spacing, shadows and radii with runtime tokens.
3. Replace arbitrary SVG/HTML with the reviewed icon vocabulary or a separately reviewed licensed asset.
4. Accept a bounded typed presentation document or the native module's typed data—not a free-form payload.
5. Add loading, empty, error, denied, long-content and narrow-screen behavior.
6. Add keyboard focus, accessible names and reduced-motion behavior.
7. Register it only if it needs to be independently placeable in Puck; otherwise keep it inside its native module.

## 7. Edit each page in Design mode

1. Open the workshop SaaS and choose **Design**.
2. Select the User Type and verify the menu that should contain the page.
3. Select the shared page and open its editor.
4. Use **Puck (primary)** to add, remove, rearrange and configure registered components.
5. Use **Monaco (advanced)** only for a canonical property that Puck cannot yet express conveniently.
6. Keep block `_id` values stable. A copied block needs a new unique ID.
7. Preserve `bindingKey`, optional `dataKey`, responsive settings, actions and security metadata.
8. Preview, save a draft with a meaningful note, validate, inspect role preview and publish only after the review matrix passes.

Page JSON arranges registered components; it does not grant access. Role preview changes presentation only. Live data continues to use the signed-in user's server-derived tenant, DataRoles and Locations.

## 8. Build responsive page compositions

Use `core.container` with the 12-column grid when hierarchy matters. For example, an eight-column primary workspace can collapse below its four-column context panel at tablet/mobile sizes:

```
{
  "_id": "primary-workspace",
  "_type": "core.card",
  "responsive": {
    "desktop": { "span": 8 },
    "tablet": { "span": 12 },
    "mobile": { "span": 12 }
  },
  "props": { "title": "Current work", "tone": "primary" },
  "children": []
}
```

- Metrics: 3/3/3/3 desktop, 6/6 tablet, 12 mobile.
- Main dashboard: 8/4 or 7/5 desktop, stacked on tablet/mobile.
- Record detail: primary record content beside related context, then one-column on narrow screens.
- Forms: one column by default; use two columns only for short naturally paired fields.

Review at approximately 1440px desktop, 1024px tablet and 390px mobile. The existing runtime changes grid spans at 1024px and 760px and adds compact component behavior below 640px.

## 9. Finish pages in a deliberate order

1. Finish one dashboard: Home or Executive Overview.
2. Finish one queue/list: Work Orders.
3. Finish one record/detail experience: Contacts or Work Order detail.
4. Use those three pages to settle the shared spacing, card, toolbar, form, table and responsive patterns.
5. Apply the stable patterns to Mail, Universal Inbox, GoClaw and AI Insights.
6. Continue through operations, collaboration, knowledge and utility pages.

Avoid bespoke restyling across every page at once. Repeated patterns will drift and the early pages will need to be redone.

## 10. Complete every real page state

For every user-managed module, review loading, empty, populated, long-content, validation-error, permission-denied, server-error, stale-write and successful-mutation states. Exercise create, view, edit/update and remove/archive, plus favorite/unfavorite, record association, files and activity where applicable.

Derived pages such as Global Search, Record Activity and audit/history remain read-only. Give them a clear path to the secured native module that owns the record instead of duplicating destructive controls.

## 11. Verify the implementation

Repository maintainers should run:

```
python -m pytest templates\professional-foundation\tests -q
npm --prefix apps\tenant-runtime test -- src\ProfessionalPrimitives.test.tsx src\PageRenderer.test.tsx src\PuckPageDesignerAdapter.test.ts src\SaasDesignStudio.test.tsx
npm --prefix apps\tenant-runtime run build
python tests\e2e\run_visual_build_proof.py --static-only
```

Then run authenticated desktop and mobile journeys against a route-resolved disposable tenant. Static preview proves layout and contracts; it does not prove live publication, permissions or database behavior.

- No inert or invented actions.
- No browser database identity, credentials or provider secrets.
- Visible controls match actual permissions and routes.
- Focus order, labels, contrast, touch targets and overflow are usable.
- Mutations refresh the affected record/list/count/favorite state.
- Long and zero-result data remain polished.

## 12. Harvest and publish the finished template

1. Finish and publish the pages in the account-owned workshop SaaS.
2. Harvest each owned Page through `POST /api/apps/{saasAppId}/template-harvests`.
3. Attach the artifacts to a draft Template Library package and validate it.
4. Publish an immutable exact version.
5. Install that exact version into a different disposable SaaS.
6. Repeat lifecycle, permission, desktop and mobile checks in the installed copy before offering it to other builders.

Important

Current template-pack members do not copy SaaS asset bytes or remap source-app asset URLs into the installed app. Public asset URLs are immutable and usable by the working source SaaS, but an asset-dependent template is not yet a self-contained exact-version install. Package-and-remap support must be completed before offering such a template as portable.

Tip

Use TailAdmin to set the quality bar. Let BuildWithHQ own the final CSS, React, data contracts and page JSON. That produces a distinctive professional SaaS without creating a fragile second application inside the platform.

Continue with the [Professional Template Foundation](professional-template-foundation.html), [page editor](page-editor.html), [React component catalog](react-component-catalog.html), and [exact-version template guide](templates-forking.html).

Compare all six styling approaches in [Support for React](support-for-react.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/tailadmin-template-design-and-react-customization.html).

---
title: "Host SaaS CSS, logos, images, and design assets"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/saas-css-and-design-assets.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Host SaaS CSS, logos, images, and design assets

Upload app-scoped assets, organize virtual folders, publish validated CSS, and use stable public asset URLs in pages and React templates.

## In brief

- **Workspace:** App Assets
- **Public base:** assets.buildwithhq.com
- **Blocked:** .dll, .com, .exe
- **Storage root:** Operator configured

**App Assets** is the design-file library for one SaaS application. It stores logos, images, fonts, videos, PDFs, downloads, and a validated app stylesheet without putting file bytes or server paths in page JSON. Public files receive an immutable URL under that SaaS app's identity.

Uploads are **private by default**. Public delivery requires an explicit selection and should be used only when a browser or published stylesheet must load the asset without an authenticated content request.

[Upload a file](#upload) [Publish CSS](#css) [Use assets in pages](#template) [Security rules](#rules) [Troubleshoot](#troubleshoot)

## Automate assets through the Developer API

A trusted developer backend has the same three styling layers as the dashboard: app-wide theme, shared assets, and page drafts/publishing. Use `GET/PUT /v1/apps/{saasAppId}/theme` with `themes.read`/`themes.write` for the theme, validated `--runtime-*` variables, and base design tokens. Use `assets.read`/`assets.write` for the asset routes. Page layout and page-level tokens use the existing page-draft, validation, history, and publish routes.

```
const api = new BuildWithHQConnector({ saasAppId, credential });
await api.uploadAsset({
  file: new Blob([css], { type: "text/css" }),
  fileName: "theme.css",
  folderPath: "theme",
  assetType: "stylesheet",
  isPublic: true,
});
```

Important

The live app credential belongs only in a trusted server or secured automation host. Browser React should receive the resulting public asset URL, never the credential.

Note

Compile Tailwind locally in the React project, then upload the production CSS. The API does not execute npm, Tailwind plugins, arbitrary JavaScript, or customer build scripts. A headless React host can use its own CSS or link the returned public stylesheet URL.

The API never accepts a database, server, storage root, storage key, tenant account, or connection string. The app boundary is derived from the credential, and the database principal has execute-only access to reviewed asset procedures with no table or DDL permissions.

## Upload and organize an asset

1. Sign in to the SaaS as an account owner and choose **Assets** in the application header.
2. Select a file and optionally enter a virtual folder such as `brand/logos`, `theme/fonts`, or `product/screenshots`.
3. Uploads start private. Select **Public design asset** only when a browser page or stylesheet must load the file directly.
4. Choose **Upload**, then copy the URL shown on the asset card.

Note

The folder is a virtual label inside the SaaS. Slashes are normalized to a stable relative path. It cannot select a drive, network share, server directory, or another SaaS app.

An explicitly public file uses:

```
https://assets.buildwithhq.com/{saasAppId}/{assetId}
```

The server assigns both GUIDs. Do not construct an asset URL from a database name, account ID, user ID, filename, or storage path.

## Publish custom CSS for one SaaS

1. Open **Custom CSS** in App Assets and paste UTF-8 CSS using the existing `--runtime-*` tokens and narrowly scoped selectors.
2. Choose **Preview CSS** and review normal, loading, empty, error, dialog, desktop, tablet, and mobile states.
3. Choose **Publish CSS**. The server validates it and saves a new immutable public `theme.css` under the virtual `theme` folder.
4. The runtime loads the newest public stylesheet once per signed-in SaaS identity; ordinary page navigation does not reload it.

A stylesheet `url(...)` may use a fragment, a root-relative application path such as `/images/logo.png`, or the same SaaS app's asset prefix. Use exact public URLs for fonts and background images.

Use literal URLs in `image-set(...)`, `-webkit-image-set(...)`, `image(...)`, and `src(...)` too. CSS escapes cannot bypass the URL policy. Image candidates containing `var(...)`, `env(...)`, or `attr(...)` are rejected because their eventual URL cannot be checked during upload; ordinary theme variables and gradients remain supported. Backslashes, protocol-relative hosts, and paths outside the app's public asset directory are rejected. The policy also applies to private stylesheet uploads.

Important

Published CSS rejects imports, executable URLs, scriptable legacy expressions, embedded markup, and remote or cross-app asset URLs. CSS cannot create an API route, grant a permission, or replace a native module action.

## Use assets in pages and React

- Use the public URL in a registered logo, image, download, poster, or bounded asset property.
- Pass the URL as data to repository-maintained React; page JSON must never become an arbitrary import path.
- Keep meaningful alternative text and responsive dimensions in the owning component.

Important

Current template-pack members do not copy asset bytes or remap source-SaaS URLs into a newly installed SaaS. Asset-dependent marketplace templates are not self-contained until exact-version asset packaging and destination remapping are implemented.

## File and delivery rules

| File | Accepted? | Public behavior |
| --- | --- | --- |
| DLL, COM, EXE | No | Rejected before storage |
| Validated CSS | Yes | Rendered as `text/css` |
| PNG, JPEG, GIF, WebP, AVIF | Yes | Rendered inline |
| MP4, WebM, WOFF, WOFF2, PDF | Yes | Rendered inline |
| HTML, SVG, scripts, archives, source, or unknown | Yes | Downloaded as an inert binary attachment with `nosniff` and sandbox policy |

Uploads retain the 25 MiB limit; CSS is limited to 512 KiB. Stored bytes are SHA-256 hashed. Removing an asset makes its URL unavailable rather than reusing its identity. Public delivery resolves the active app and retrieves only explicitly public metadata; the browser receives no storage key, path, database coordinate, or credential.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Upload rejected | Check the extension, simple filename, virtual-folder traversal, and 25 MiB limit. |
| CSS rejected | Remove imports, executable or remote URLs, embedded markup, and unsupported encoding; remain below 512 KiB. |
| Public URL returns 404 | Confirm the asset is public, active, not removed, and belongs to the URL's SaaS app. |
| Asset host cannot connect | Have the operator verify DNS, TLS, reverse proxy, and preserved Host routing. |
| New CSS is absent | Confirm publish succeeded, reload once, and inspect `link#bwhq-published-theme-css`. |

Operators should continue with [Deploy the SaaS asset domain and storage root](../partners/asset-domain-and-storage-deployment.html). Template maintainers should also read [Apply a TailAdmin-style design](tailadmin-template-design-and-react-customization.html).

Compare all six styling approaches in [Support for React](support-for-react.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/saas-css-and-design-assets.html).

---
title: "Convert HTML into BuildWithHQ/Puck pages"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/html-to-puck-converter.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Convert HTML into BuildWithHQ/Puck pages

Turn static HTML or a frontend build entry into deterministic, validated Professional Foundation page JSON without importing arbitrary code or authority.

## In brief

- **Input:** HTML file or dist/index.html
- **Output:** Canonical Puck page JSON
- **Security:** No scripts, secrets, or inferred bindings

Developer Kit 1.20.70 includes `tools/html_to_puck.py`, an offline converter for bringing the useful structure of an existing static design into the current BuildWithHQ page system. It accepts one HTML file or a directory whose entry is `index.html`, then emits real page JSON made only from registered Professional Foundation component keys.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Edit bindings in local Puck](local-puck-binding-editor.html) [Component and theme guide](professional-template-foundation.html) [Page editor guide](page-editor.html)

Note

This is a design migration helper, not a compiled-application loader. A Vite dist directory supplies its index.html as input; JavaScript chunks, source maps, CSS bundles, credentials and asset files are never embedded in page JSON.

## Run the converter

### Windows PowerShell

```
# From the extracted Developer Kit 1.20.70 directory
python .\tools\html_to_puck.py .\dist `
  --output .\converted\home.page.json `
  --report .\converted\home.report.json

# Reject the conversion if any executable/unsupported content was discarded.
python .\tools\html_to_puck.py .\source.html `
  --output .\converted\source.page.json `
  --report .\converted\source.report.json `
  --strict
```

### Linux or macOS

```
# From the extracted Developer Kit 1.20.70 directory
python3 ./tools/html_to_puck.py ./dist \
  --output ./converted/home.page.json \
  --report ./converted/home.report.json

python3 ./tools/html_to_puck.py ./source.html \
  --output ./converted/source.page.json \
  --report ./converted/source.report.json \
  --strict
```

Use `--entry another.html` when a directory has a different entry filename. The converter uses only Python's standard library and makes no network, API or database connection.

## What becomes a Puck component

| HTML intent | BuildWithHQ output | Behavior |
| --- | --- | --- |
| First `h1` | `core.page-header` | Page title with a stable generated block ID. |
| Other headings and paragraphs | `core.text` | Escaped display text; markup does not become executable HTML. |
| `section`, `article`, `aside` | `core.card` | First heading/paragraph become title/description; remaining content stays nested. |
| Grid/flex structural containers | `core.container` | Preserves stack, row or automatic-grid intent and simple gaps. |
| Lists | `core.list-row` | Bounded display rows inside a stack. |
| HTML tables | `core.data-table` | At most 24 columns and 500 static preview rows. |

Repeated conversion with the same seed and source order produces the same block IDs. This makes source review and page diffs meaningful. Input is capped at 2 MiB, output at 5,000 blocks, nesting at 32 levels and charts at 60 finite values.

## Annotate HTML when you want an exact component

Use `data-bwhq-component` with a public registry key and allowlisted `data-bwhq-*` properties. Unknown components, icons, tones, enum values, properties and responsive spans fail closed.

```
<div class="grid gap-4" data-bwhq-component="core.container">
  <div
    data-bwhq-component="core.stat-tile"
    data-bwhq-label="Open work"
    data-bwhq-value="42"
    data-bwhq-delta="6 today"
    data-bwhq-direction="up"
    data-bwhq-icon-name="work-order"
    data-bwhq-tone="primary"
    data-bwhq-desktop-span="3"
    data-bwhq-tablet-span="6"
    data-bwhq-mobile-span="12">
  </div>
</div>
```

For chart arrays or other richer preview properties, `data-bwhq-props` accepts a JSON object and applies the same property allowlist. It cannot introduce binding identity, authorization identity or executable code.

## Review the loss report

The report counts stripped scripts/styles/iframes, removed event handlers, display-only links/buttons, omitted media, ignored asset URLs, rejected authority attributes, component totals and any bounded text/table shortening. Credential-shaped `bwk_` and `bwu_` tokens are redacted from visible text and attributes and counted by location without copying the secret into the report. With `--strict`, a lossy conversion returns exit code 2 and does not write the page file; the report is still written for review.

Important

Links, buttons and form controls do not become working writes. Add interactions after conversion through registered components and closed action keys mapped to reviewed APIs. Never recreate an onclick handler or infer an API route from HTML.

## Set data bindings outside Puck

Puck is optional for binding assignment. Open the generated page JSON in a text editor, source-controlled build step or custom authoring tool. Put `bindingKey` and optional `dataKey` directly on the target block, beside `_id`, `_type` and `props`.

```
{
  "_id": "home-work-table",
  "_type": "core.presentation-grid",
  "bindingKey": "work-orders.presentation",
  "dataKey": "table",
  "props": {}
}
```

The deterministic `_id` gives automation a stable target. Several blocks may share one registered binding and select bounded children such as `metrics`, `recent`, `table` or `timeline` with `dataKey`. A data key is only a safe path into returned JSON; it is not SQL, a filter expression or authorization.

The binding must already be installed and registered for that SaaS. Adding an unknown key does not create a binding: server validation rejects the page and runtime resolution fails closed. Get the current `pageVersion`, save the edited document with `BuildWithHQDesignClient.saveDraft` and `expectedPageVersion`, then call `validatePage`. Keep the `bwk_draft_` credential on a trusted server.

Note

The converter refuses binding attributes in source HTML on purpose. Assigning bindings after conversion prevents downloaded markup from selecting a data source or carrying tenant, account, user, role or location identity into the page.

## Make the converted design live

1. Open the generated JSON in Puck or an external JSON workflow and review desktop, tablet, mobile, keyboard, empty and long-content behavior.
2. Replace static preview values with registered binding keys. The server must still derive the SaaS app, AppAccount, user, DataRoles and Locations.
3. Add forms, checkboxes, uploads and actions using existing first-class module components and reviewed API handlers.
4. Save the page as an unpublished draft with the server-only `BuildWithHQDesignClient` (or `bwhq page save`) and a `bwk_draft_` credential.
5. Run server validation. Publish the exact draft history only with a separate `bwk_live_` credential carrying `pages.publish`.

The static page works immediately in Puck. Live data and writes work when explicitly connected to the platform's real secured contracts—there are no generated placeholder routes or fake bindings.

## Complete annotated example

**HTML input included in the ZIP**

```
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Operations control panel</title>
  <style>body { font-family: system-ui; }</style>
</head>
<body>
  <main class="flex flex-col gap-4">
    <h1>Operations control panel</h1>
    <p>Review current workload, service health, and team activity.</p>

    <div class="grid gap-4" data-bwhq-component="core.container">
      <div data-bwhq-component="core.stat-tile" data-bwhq-label="Open work" data-bwhq-value="42" data-bwhq-delta="6 today" data-bwhq-direction="up" data-bwhq-icon-name="work-order" data-bwhq-tone="primary" data-bwhq-desktop-span="4" data-bwhq-tablet-span="6" data-bwhq-mobile-span="12"></div>
      <div data-bwhq-component="core.stat-tile" data-bwhq-label="Within service level" data-bwhq-value="96%" data-bwhq-delta="2% this week" data-bwhq-direction="up" data-bwhq-icon-name="check-circle" data-bwhq-tone="success" data-bwhq-desktop-span="4" data-bwhq-tablet-span="6" data-bwhq-mobile-span="12"></div>
      <div data-bwhq-component="core.stat-tile" data-bwhq-label="Needs attention" data-bwhq-value="7" data-bwhq-delta="2 overdue" data-bwhq-direction="down" data-bwhq-icon-name="bell" data-bwhq-tone="warning" data-bwhq-desktop-span="4" data-bwhq-tablet-span="12" data-bwhq-mobile-span="12"></div>
    </div>

    <section class="primary">
      <h2>Priority work</h2>
      <p>A bounded preview that can be replaced with a reviewed live binding.</p>
      <table>
        <caption>Today's work queue</caption>
        <thead><tr><th>Reference</th><th>Summary</th><th>Owner</th><th>Status</th></tr></thead>
        <tbody>
          <tr><td>WO-1048</td><td>Inspect cooling system</td><td>Morgan Lee</td><td>In progress</td></tr>
          <tr><td>TK-318</td><td>Confirm access window</td><td>Avery Patel</td><td>Waiting</td></tr>
          <tr><td>AP-092</td><td>Approve completion proof</td><td>Riley Chen</td><td>Review</td></tr>
        </tbody>
      </table>
    </section>

    <section>
      <h2>Next actions</h2>
      <p>Display-only list imported from HTML.</p>
      <ul>
        <li>Review two overdue tickets</li>
        <li>Confirm tomorrow's technician schedule</li>
        <li>Approve completed checklist evidence</li>
      </ul>
    </section>
  </main>
</body>
</html>
```

**Exact generated Puck page included in the ZIP**

```
{
  "blocks": [
    {
      "_id": "html-control-panel-0014-c80bd7a308",
      "_type": "core.container",
      "props": {
        "layout": "stack",
        "gap": "normal"
      },
      "children": [
        {
          "_id": "html-control-panel-0001-5b3859c95a",
          "_type": "core.page-header",
          "props": {
            "title": "Operations control panel"
          }
        },
        {
          "_id": "html-control-panel-0002-aa94387df2",
          "_type": "core.text",
          "props": {
            "text": "Review current workload, service health, and team activity.",
            "variant": "body",
            "align": "left"
          }
        },
        {
          "_id": "html-control-panel-0006-9d2e403adf",
          "_type": "core.container",
          "props": {
            "layout": "grid",
            "gridMode": "auto-fit",
            "gap": "normal"
          },
          "children": [
            {
              "_id": "html-control-panel-0003-c53609701a",
              "_type": "core.stat-tile",
              "props": {
                "tone": "primary",
                "label": "Open work",
                "value": "42",
                "direction": "up",
                "delta": "6 today",
                "iconName": "work-order",
                "responsive": {
                  "desktop": { "span": 4 },
                  "tablet": { "span": 6 },
                  "mobile": { "span": 12 }
                }
              }
            },
            {
              "_id": "html-control-panel-0004-53f4f0b16d",
              "_type": "core.stat-tile",
              "props": {
                "tone": "success",
                "label": "Within service level",
                "value": "96%",
                "direction": "up",
                "delta": "2% this week",
                "iconName": "check-circle",
                "responsive": {
                  "desktop": { "span": 4 },
                  "tablet": { "span": 6 },
                  "mobile": { "span": 12 }
                }
              }
            },
            {
              "_id": "html-control-panel-0005-51eb9b8be4",
              "_type": "core.stat-tile",
              "props": {
                "tone": "warning",
                "label": "Needs attention",
                "value": "7",
                "direction": "down",
                "delta": "2 overdue",
                "iconName": "bell",
                "responsive": {
                  "desktop": { "span": 4 },
                  "tablet": { "span": 12 },
                  "mobile": { "span": 12 }
                }
              }
            }
          ]
        },
        {
          "_id": "html-control-panel-0008-a56413e43e",
          "_type": "core.card",
          "props": {
            "tone": "primary",
            "title": "Priority work",
            "description": "A bounded preview that can be replaced with a reviewed live binding."
          },
          "children": [
            {
              "_id": "html-control-panel-0007-bda86f9048",
              "_type": "core.data-table",
              "props": {
                "caption": "Today's work queue",
                "columns": [
                  { "key": "reference", "label": "Reference", "align": "left" },
                  { "key": "summary", "label": "Summary", "align": "left" },
                  { "key": "owner", "label": "Owner", "align": "left" },
                  { "key": "status", "label": "Status", "align": "left" }
                ],
                "rows": [
                  { "reference": "WO-1048", "summary": "Inspect cooling system", "owner": "Morgan Lee", "status": "In progress" },
                  { "reference": "TK-318", "summary": "Confirm access window", "owner": "Avery Patel", "status": "Waiting" },
                  { "reference": "AP-092", "summary": "Approve completion proof", "owner": "Riley Chen", "status": "Review" }
                ]
              }
            }
          ]
        },
        {
          "_id": "html-control-panel-0013-76a243792d",
          "_type": "core.card",
          "props": {
            "tone": "neutral",
            "title": "Next actions",
            "description": "Display-only list imported from HTML."
          },
          "children": [
            {
              "_id": "html-control-panel-0012-b612166a0a",
              "_type": "core.container",
              "props": {
                "layout": "stack",
                "gap": "compact"
              },
              "children": [
                {
                  "_id": "html-control-panel-0009-c28519306d",
                  "_type": "core.list-row",
                  "props": { "primary": "Review two overdue tickets", "tone": "neutral" }
                },
                {
                  "_id": "html-control-panel-0010-0bc1e38bf4",
                  "_type": "core.list-row",
                  "props": { "primary": "Confirm tomorrow's technician schedule", "tone": "neutral" }
                },
                {
                  "_id": "html-control-panel-0011-a53fc93bed",
                  "_type": "core.list-row",
                  "props": { "primary": "Approve completed checklist evidence", "tone": "neutral" }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

## Verify the tool

```
python .\tools\html_to_puck.py --self-test
python -m pytest templates\professional-foundation\tests\test_html_to_puck.py -q
```

Tip

Use this converter to accelerate a migration, then let Puck and the component registry own the page. Keep the original HTML as design reference, not as a second production renderer.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/html-to-puck-converter.html).

---
title: "Run Puck locally and assign data bindings"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/local-puck-binding-editor.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Run Puck locally and assign data bindings

Open canonical BuildWithHQ page JSON in a self-contained local Puck editor, assign registered binding keys, and save a validated unpublished draft without exposing credentials to Vite.

## In brief

- **Editor:** Puck 0.23.0
- **Browser access:** Local files only
- **Remote save:** Trusted Node command

Developer Kit 1.20.70 contains a complete local Puck editor under `local-puck/`. It uses the same pinned Puck adapter, canonical page conversion, component catalogs and validation rules as the hosted BuildWithHQ designer. It is not a lookalike editor and it does not introduce another page format.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Convert existing HTML first](html-to-puck-converter.html) [Component and theme guide](professional-template-foundation.html)

Note

The local browser opens and downloads files only. It receives no app credential, tenant data, database route, user identity, DataRole or Location. A separate Node command performs the optional authenticated draft save.

## Start the local editor

### Windows PowerShell

```
Expand-Archive .\BuildWithHQ-API43-Developer-Kit-1.20.70.zip .\bwhq-kit
cd .\bwhq-kit\local-puck
npm ci
npm run dev
```

### Linux or macOS

```
unzip BuildWithHQ-API43-Developer-Kit-1.20.70.zip -d bwhq-kit
cd bwhq-kit/local-puck
npm ci
npm run dev
```

Open `http://127.0.0.1:4175`. The server binds only to loopback and applies a restrictive local Content Security Policy. Dependency versions are pinned in `package-lock.json`, so use `npm ci`.

## Assign a binding visually

1. Select **Open page JSON** and choose a converted or existing canonical page file.
2. Select the block that should receive live data.
3. Choose a shipped key in **API data binding key (optional)**. The closed list comes from `catalog/bindings.json`, not a guessed module name.
4. Choose its bounded child path in **Nested API data path (optional)**.
5. Use **Advanced** only when this SaaS has separately installed a registered binding that is not in the distributed golden catalog. Manual text still has to pass real server validation.
6. Select **Save draft** or **Download JSON**. Both produce canonical BuildWithHQ page JSON; neither publishes.

```
{
  "_id": "home-work-table",
  "_type": "core.presentation-grid",
  "bindingKey": "work-orders.presentation",
  "dataKey": "table",
  "props": {}
}
```

Multiple blocks can reuse one binding and select different children. For example, a page can bind metrics, progress, a table and timeline to `work-orders.presentation` while choosing `metrics`, `byStatus`, `table` and `timeline` through each block's `dataKey`. The server executes the binding once under the signed-in user's real scope; the browser does not load a broad dataset and aggregate it itself.

Note

capabilities.json inventories modules and API routes; it is not an installed-binding registry. The separate bindings.json file contains the three presentation bindings shipped by the current golden tenant template: Work Orders, Checklists & Signoffs, and Contacts.

## What the editor can and cannot create

| Local action | Result |
| --- | --- |
| Set `bindingKey` | References an already installed and active server binding. |
| Set `dataKey` | Selects a bounded property from that binding's returned JSON document. |
| Type an unknown key | Does not create an API or SQL query; real server validation rejects the draft. |
| Download JSON | Writes a local canonical page document suitable for Git review, Puck, Monaco or the draft API. |
| Save through the trusted command | Uses the current page-version fence, creates immutable draft history and immediately runs server validation. |
| Publish | Not available in the local editor or draft command. Publication requires a separate live credential and exact validated history. |

## Save and validate a real unpublished draft

Keep the `bwk_draft_` credential in the terminal environment. Never put it in a `VITE_*` variable, frontend source, page JSON, browser storage or Git.

### Windows PowerShell

```
$env:BWHQ_SAAS_APP_ID = Read-Host "SaaS app ID"
$env:BWHQ_DRAFT_CREDENTIAL = Read-Host "Draft credential"
npm run save-draft -- --page .\home.page.json --page-key Home `
  --change-note "Local Puck binding edit"
```

### Linux or macOS

```
read -rp "SaaS app ID: " BWHQ_SAAS_APP_ID && export BWHQ_SAAS_APP_ID
read -rsp "Draft credential: " BWHQ_DRAFT_CREDENTIAL && export BWHQ_DRAFT_CREDENTIAL
npm run save-draft -- --page ./home.page.json --page-key Home \
  --change-note "Local Puck binding edit"
```

`save-draft.mjs` calls the real Developer API. It gets the current `pageVersion`, saves with `expectedPageVersion`, then calls validation and returns the immutable `pageHistoryId`. A validation failure exits non-zero. The command never publishes and never logs the credential.

Important

A page can only reference a registered binding. Creating a new binding is a separate reviewed template/application contract. It must define a bounded operation and output shape and retain server-derived SaaS, AppAccount, user, DataRole and Location scope.

## Verify before use

```
npm ci
npm run build
```

The Developer Kit release gate also compares the distributed Puck adapter and page runtime with their production sources, hashes every local-editor file in the integrity manifest, and builds the extracted app before release.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/local-puck-binding-editor.html).

---
title: "Binding Contracts"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/binding-contracts.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Binding Contracts

Use the binding catalog and live checklist/contacts page contract to connect React template blocks to bounded, authorized server data and actions.

## In brief

- **Catalog bindings:** 4
- **Live example:** Checklist + Contacts
- **Browser SQL access:** Never
- **Authorization:** Server enforced

A binding contract connects a React template block to an installed, bounded server operation. The page stores a public `bindingKey` and an optional `dataKey`; it stores no SQL, database route, tenant identity, credential or authorization rule.

[Binding catalog](#binding-catalog) [Live checklist contract](#live-checklist-contracts) [Runtime flow](#runtime) [Actions and refresh](#actions) [Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip)

Note

The binding catalog is an authoring allowlist. It tells Puck which installed keys and child data paths a builder may select. It does not grant access to records or actions.

## Binding catalog

The current local Puck catalog is `developer-kit/local-puck/binding-catalog.json`. Each entry gives the stable binding name and the bounded child documents that blocks may select with `dataKey`.

| Binding key | Purpose | Available data keys |
| --- | --- | --- |
| `work-orders.presentation` | Work Orders presentation | `metrics`, `byStatus`, `recent`, `trend`, `table`, `timeline` |
| `checklists-signoffs.presentation` | Checklists & Signoffs presentation | `tasks` |
| `contacts.presentation` | Contacts presentation | `table` |
| `company-news.presentation` | Company News presentation | `table`, `feed`, `metrics` |

**Copy the complete binding catalog**

```
{
  "schemaVersion": 1,
  "bindings": [
    {
      "bindingKey": "work-orders.presentation",
      "title": "Work Orders presentation",
      "dataKeys": ["metrics", "byStatus", "recent", "trend", "table", "timeline"]
    },
    {
      "bindingKey": "checklists-signoffs.presentation",
      "title": "Checklists & Signoffs presentation",
      "dataKeys": ["tasks"]
    },
    {
      "bindingKey": "contacts.presentation",
      "title": "Contacts presentation",
      "dataKeys": ["table"]
    },
    {
      "bindingKey": "company-news.presentation",
      "title": "Company News presentation",
      "dataKeys": ["table", "feed", "metrics"]
    }
  ]
}
```

Several blocks can reuse one binding. For example, Work Orders can render metrics, a status distribution, recent records, a trend, a grid and a timeline from one authorized presentation document. Reuse avoids issuing a broad record query for every visual block.

## Live checklist and Contacts page contract

The shipped `pages/live-checklist-contacts.json` example composes two independent live contracts. The checklist task list uses `checklists-signoffs.presentation` with `dataKey: tasks`. The Contacts grid uses `contacts.presentation` with `dataKey: table`.

**Copy the complete live checklist and Contacts page JSON**

```
{
  "blocks": [
    {
      "_id": "live-actions-header",
      "_type": "core.page-header",
      "props": {
        "title": "Live checklist and contact actions",
        "lead": "These components receive only the records and actions authorized for the signed-in user. Checklist toggles use optimistic concurrency; contact actions refetch their scoped presentation after each write."
      }
    },
    {
      "_id": "live-actions-layout",
      "_type": "core.container",
      "props": {
        "layout": "grid",
        "gridMode": "twelve-column",
        "gap": "normal"
      },
      "children": [
        {
          "_id": "live-actions-checklist-card",
          "_type": "core.card",
          "props": {
            "title": "Checklist work",
            "description": "Items outside the user's DataRole and Location scope are never sent to the browser.",
            "responsive": {
              "desktop": { "span": 5 },
              "tablet": { "span": 12 },
              "mobile": { "span": 12 }
            }
          },
          "children": [
            {
              "_id": "live-actions-checklist",
              "_type": "core.task-list",
              "bindingKey": "checklists-signoffs.presentation",
              "dataKey": "tasks",
              "props": {}
            }
          ]
        },
        {
          "_id": "live-actions-contacts-card",
          "_type": "core.card",
          "props": {
            "title": "Recent contacts",
            "description": "The grid is bounded to 25 visible contacts and each row declares only its currently valid favorite action.",
            "responsive": {
              "desktop": { "span": 7 },
              "tablet": { "span": 12 },
              "mobile": { "span": 12 }
            }
          },
          "children": [
            {
              "_id": "live-actions-contacts",
              "_type": "core.presentation-grid",
              "bindingKey": "contacts.presentation",
              "dataKey": "table",
              "props": {}
            }
          ]
        }
      ]
    }
  ]
}
```

The layout and presentation remain editable. Changing card widths, titles, responsive spans or component styling does not change the server contract. Changing a `bindingKey` or `dataKey` must still reference an installed catalog entry and pass server validation.

## How the runtime resolves a binding

1. The page renderer collects unique binding keys from visible, registered blocks.
2. The native runtime requests `GET /api/runtime/data/<bindingKey>` under the current same-origin user session. Headless applications can resolve 1–24 keys with `POST /v1/apps/{saasAppId}/runtime/bindings` and a delegated-user credential.
3. The server resolves the tenant from the real host and requires the authenticated SaaS app, AppAccount and user context.
4. The registered binding chooses a reviewed stored procedure. That procedure applies tenant, DataRole, Location, record visibility, soft-delete and action-entitlement rules before returning JSON.
5. The React block receives a typed loading/data/error state and selects only its configured `dataKey`.

A native binding response has this envelope:

```
{
  "contractVersion": 1,
  "bindingKey": "checklists-signoffs.presentation",
  "data": {
    "tasks": {
      "presentationVersion": 1,
      "kind": "task-list",
      "items": []
    }
  }
}
```

Important

A page definition is presentation, not data authority. Never replace a binding with browser SQL, a connector secret, an arbitrary stored-procedure name or a client-supplied SaaS/AppAccount/User identifier.

## Live actions, revisions and exact refresh

Bindings are read contracts. A checklist toggle or Contacts favorite uses the separate Lego action broker at `POST /api/runtime/lego/actions`. The rendered row receives only server-issued record, field and action identifiers that are currently available to that user.

```
{
  "contractVersion": 1,
  "pageKey": "LiveChecklistContacts",
  "blockId": "live-actions-checklist",
  "actionId": "server-issued-action-guid",
  "recordId": "server-issued-record-guid",
  "expectedRevision": 7,
  "values": {
    "checked": true
  }
}
```

1. The browser sends the saved page key, block ID, server-issued action ID, record ID, expected revision when required, and validated input values.
2. The broker reloads the saved page and catalog, confirms that the block declares the action, then calls the typed module service.
3. The endpoint and stored procedure independently re-authorize the operation. A displayed action ID is user-interface intent, not proof of permission.
4. A successful result names the exact binding that became stale. React reloads only that binding with `?refresh=true`.
5. A stale checklist revision returns HTTP 409. The optimistic state is removed, the current binding is fetched again, and the user can retry against the current revision.

## Use these contracts in a template

1. Open the page in hosted Puck or the local Puck editor.
2. Select a data-aware block such as `core.task-list` or `core.presentation-grid`.
3. Choose its `bindingKey` from the binding catalog.
4. Choose a `dataKey` declared by that catalog entry.
5. Save and validate the draft, then publish it through the normal version-fenced workflow.
6. Exercise loading, empty, populated, forbidden, stale-write and successful-mutation states with a real route-resolved disposable tenant.

An unknown binding name does not create an API or query. Adding a binding is a separate reviewed application contract with a stable key, approved stored procedure, mandatory server context, bounded output schema, cache policy and authorization tests.

Continue with [the local Puck binding editor](local-puck-binding-editor.html), [interactive API presentations](interactive-api-presentations.html), and [the headless application kit](headless-application-kit.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/binding-contracts.html).

---
title: "Interactive API presentations for professional admin pages"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/interactive-api-presentations.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Interactive API presentations for professional admin pages

Build API-bound KPI strips, names and statuses, progress, charts, sortable grids and timelines from one bounded server-scoped presentation contract.

## In brief

- **Presentation blocks:** 6
- **Batch bindings:** Up to 24
- **Browser data source:** Secured APIs
- **SQL in React:** Never

Interactive API presentations let a designer turn one secured business capability into KPI cards, names and statuses, distributions, time-series charts, sortable visible-page grids and activity timelines. The browser consumes APIs — never SQL — while the server keeps routing, joins, authorization and result shaping behind reviewed contracts.

[What designers can do](#capabilities) [How it works](#flow) [Six shapes](#vocabulary) [Copy the page](#page-json) [Call the API](#api) [Headless React](#headless) [Add a module](#add-module) [Limits](#limits) [Verify](#verify)

Note

This is an additive presentation layer. Existing module APIs remain the source for create, update, delete and detail journeys. A presentation binding summarizes or composes those capabilities for a particular screen; it does not turn every CRUD endpoint into an unbounded dashboard query.

## What designers can do now

- Place responsive KPI strips, entity/name lists, status distributions, interactive bar or line charts, typed sortable grids and activity timelines on any authored page.
- Bind several blocks to one API result. The renderer deduplicates visible binding keys, makes one batch request, and uses each block's `dataKey` to select its child document.
- Mix presentation blocks with first-class modules, menus, forms, Files, Workflow, Universal Inbox and ordinary layout components.
- Use Puck to change safe scalar properties while preserving binding identity, exact-version publication and the registry-backed renderer vocabulary.
- Apply a SaaS theme through design tokens and CSS variables, or use the normalized contracts in a completely custom headless React design.
- Receive explicit loading, empty and safe error states without sending raw rows to the browser and filtering them there.
- Keep stable `recordId` values on list, grid and timeline items so a row can open the correct authorized detail journey.

## How one request can power a complete admin page

```
Authored Page
  └─ collect unique visible bindingKey values
       └─ POST /api/runtime/data/batch (maximum 24 keys)
            └─ verified host + tenant session + server-side routing
                 └─ reviewed binding contracts (maximum 4 in flight)
                      └─ bounded, already-authorized presentation documents
                           ├─ metrics     → core.metric-strip
                           ├─ byStatus    → core.progress-list
                           ├─ recent      → core.entity-list
                           ├─ trend       → core.series-chart
                           ├─ table       → core.presentation-grid
                           └─ timeline    → core.timeline
```

Repeated use of `work-orders.presentation` is intentional. The page renderer requests that key once, shares the result, and lets each block read only `metrics`, `byStatus`, `recent`, `trend`, `table` or `timeline`. Hidden, unauthorized and unknown blocks do not cause data requests.

## The six normalized API shapes

| Kind | Registry block | Use it for | Hard maximum |
| --- | --- | --- | --- |
| `metric-set` | `core.metric-strip` | Counts, currency, percent, duration and deltas | 12 metrics |
| `entity-list` | `core.entity-list` | Names, images, context, status and trailing values | 100 items |
| `progress-list` | `core.progress-list` | Status mix, ranked progress and capacity | 100 items |
| `series-chart` | `core.series-chart` | Interactive bar/line periods with an accessible value table | 5 periods; 8 series; 120 points each |
| `data-grid` | `core.presentation-grid` | Typed visible-page rows and local sorting | 24 columns; 500 rows |
| `timeline` | `core.timeline` | Chronological activity, actor and status | 100 items |

Every child declares `presentationVersion: 1` and an exact `kind`. Keys, statuses, tones, URLs, timestamps, arrays and finite numbers are parsed fail-closed before rendering.

**Copy a complete batch response example**

```
{
  "contractVersion": 1,
  "bindings": [
    {
      "bindingKey": "work-orders.presentation",
      "status": "ok",
      "data": {
        "metrics": {
          "presentationVersion": 1,
          "kind": "metric-set",
          "title": "Work order overview",
          "items": [
            { "key": "open", "label": "Open", "value": 24, "format": "number", "tone": "primary" }
          ]
        },
        "recent": {
          "presentationVersion": 1,
          "kind": "entity-list",
          "title": "Recent work orders",
          "items": [
            {
              "id": "<work-order-id>",
              "recordId": "<record-id>",
              "primary": "WO-1048 · Inspect cooling system",
              "secondary": "North campus",
              "tertiary": "Urgent",
              "status": { "key": "in-progress", "label": "In progress", "tone": "primary" },
              "trailing": 2,
              "trailingLabel": "assignees"
            }
          ],
          "hasMore": false
        },
        "byStatus": {
          "presentationVersion": 1,
          "kind": "progress-list",
          "title": "Work orders by status",
          "items": [
            { "key": "requested", "label": "Requested", "value": 7, "maximum": 24, "displayValue": "7", "tone": "warning" }
          ]
        },
        "trend": {
          "presentationVersion": 1,
          "kind": "series-chart",
          "title": "Updated work orders by current status",
          "variant": "line",
          "defaultPeriodKey": "d7",
          "periods": [
            {
              "key": "d7",
              "label": "7 days",
              "labels": ["09/01", "09/02", "09/03"],
              "series": [
                { "key": "active", "label": "Active", "tone": "primary", "values": [3, 5, 4] }
              ]
            }
          ]
        },
        "table": {
          "presentationVersion": 1,
          "kind": "data-grid",
          "title": "Visible work orders",
          "columns": [
            { "key": "number", "label": "Work order", "type": "text", "align": "left" },
            { "key": "status", "label": "Status", "type": "status", "align": "left" }
          ],
          "rows": [
            {
              "id": "<work-order-id>",
              "recordId": "<record-id>",
              "cells": {
                "number": "WO-1048",
                "status": { "key": "in-progress", "label": "In progress", "tone": "primary" }
              }
            }
          ],
          "page": { "pageNumber": 1, "pageSize": 25, "hasMore": false, "totalRecords": 1, "totalIsExact": true }
        },
        "timeline": {
          "presentationVersion": 1,
          "kind": "timeline",
          "title": "Recently updated work orders",
          "items": [
            {
              "id": "<event-id>",
              "recordId": "<record-id>",
              "occurredUtc": "2026-09-04T18:00:00Z",
              "title": "WO-1048 updated",
              "description": "Inspect cooling system",
              "actor": "Avery Chen",
              "tone": "primary",
              "status": { "key": "in-progress", "label": "In progress", "tone": "primary" }
            }
          ],
          "hasMore": false
        }
      }
    }
 ]
}
```

## Copy the native styled Work Orders page

This is the complete page installed and browser-tested in the retained battle SaaS. Paste it into the advanced Page JSON editor, or recreate it visually in Puck. The system theme supplies the polish; there is no page-local CSS or script.

```
{
  "blocks": [
    {
      "_id": "work-order-command-center-header",
      "_type": "core.page-header",
      "props": {
        "title": "Work order command center",
        "lead": "Live workload, status, trends and recent activity from one server-scoped API presentation.",
        "breadcrumb": ["Operations", "Work orders"]
      }
    },
    {
      "_id": "work-order-command-center-metrics",
      "_type": "core.metric-strip",
      "bindingKey": "work-orders.presentation",
      "dataKey": "metrics",
      "props": {}
    },
    {
      "_id": "work-order-command-center-summary",
      "_type": "core.container",
      "props": {
        "layout": "grid"
      },
      "children": [
        {
          "_id": "work-order-command-center-status",
          "_type": "core.progress-list",
          "bindingKey": "work-orders.presentation",
          "dataKey": "byStatus",
          "props": {}
        },
        {
          "_id": "work-order-command-center-recent",
          "_type": "core.entity-list",
          "bindingKey": "work-orders.presentation",
          "dataKey": "recent",
          "props": {}
        }
      ]
    },
    {
      "_id": "work-order-command-center-trend",
      "_type": "core.series-chart",
      "bindingKey": "work-orders.presentation",
      "dataKey": "trend",
      "props": {}
    },
    {
      "_id": "work-order-command-center-table",
      "_type": "core.presentation-grid",
      "bindingKey": "work-orders.presentation",
      "dataKey": "table",
      "props": {}
    },
    {
      "_id": "work-order-command-center-timeline",
      "_type": "core.timeline",
      "bindingKey": "work-orders.presentation",
      "dataKey": "timeline",
      "props": {}
    }
  ]
}
```

The chart period buttons and visible-page grid sorting are interactive. The chart keeps an accessible table, the grid exposes `aria-sort`, entity metadata stacks on small screens, and wide grids scroll inside their card rather than widening the document.

## Call the presentation API directly

Inside the native runtime, use `loadRuntimeDataBindings` or the official tenant-session transport. It owns bearer authentication, refresh rotation, CSRF, same-origin credentials and safe error handling. Do not copy an access token into page JSON or call raw `fetch` without that lifecycle.

```
POST /api/runtime/data/batch
Content-Type: application/json
Authorization: Bearer <tenant access token>
X-CSRF-Token: <same-origin CSRF token>

{
  "bindingKeys": ["work-orders.presentation"]
}
```

**Copy a typed loader with strict response parsing**

```
import {
  parseDataGridPresentation,
  parseEntityListPresentation,
  parseMetricSetPresentation,
  parseProgressListPresentation,
  parseRuntimeDataBindingBatch,
  parseSeriesChartPresentation,
  parseTimelinePresentation,
} from "@buildwithhq/page-runtime";

// Use the official tenant-session transport here. It must add the bearer token,
// same-origin CSRF header, correlation ID, refresh-once behavior and safe errors.
export type AuthorizedFetch = (
  input: RequestInfo | URL,
  init?: RequestInit,
) => Promise<Response>;

export async function loadWorkOrderPresentation(
  authorizedFetch: AuthorizedFetch,
  signal?: AbortSignal,
) {
  const bindingKeys = ["work-orders.presentation"] as const;
  const response = await authorizedFetch("/api/runtime/data/batch", {
    method: "POST",
    body: JSON.stringify({ bindingKeys }),
    signal,
  });
  if (!response.ok) throw new Error("The command center could not be loaded.");

  const batch = parseRuntimeDataBindingBatch(await response.json(), bindingKeys);
  const item = batch.bindings[0];
  if (item.status !== "ok" || !item.data || Array.isArray(item.data) || typeof item.data !== "object") {
    throw new Error("The command center could not be loaded.");
  }

  return {
    metrics: parseMetricSetPresentation(item.data.metrics),
    recent: parseEntityListPresentation(item.data.recent),
    byStatus: parseProgressListPresentation(item.data.byStatus),
    trend: parseSeriesChartPresentation(item.data.trend),
    table: parseDataGridPresentation(item.data.table),
    timeline: parseTimelinePresentation(item.data.timeline),
  };
}
```

A batch returns one item per requested key in request order. Each item is independently `ok`, `notFound`, `forbidden`, `invalid` or `error`, so one unavailable panel does not require discarding successful siblings.

## Copy an unstyled/headless React composition

This version deliberately contains semantic HTML and no design opinion. Keep the typed loader, replace the markup with your design system, and style it as aggressively as you like. The authorization and cardinality boundary remains the API response, not the component.

```
import { useEffect, useRef, useState } from "react";
import type { AuthorizedFetch } from "./workOrderPresentation";
import { loadWorkOrderPresentation } from "./workOrderPresentation";

type Presentation = Awaited<ReturnType<typeof loadWorkOrderPresentation>>;

export function HeadlessWorkOrderCommandCenter({
  authorizedFetch,
}: {
  authorizedFetch: AuthorizedFetch;
}) {
  const [read, setRead] = useState<{
    owner: AuthorizedFetch;
    retry: number;
    value: Presentation | null;
    failed: boolean;
  } | null>(null);
  const [retry, setRetry] = useState(0);
  const progress = useRef<HTMLParagraphElement>(null);
  const retryButton = useRef<HTMLButtonElement>(null);

  useEffect(() => {
    const request = new AbortController();
    let active = true;
    setRead({ owner: authorizedFetch, retry, value: null, failed: false });
    loadWorkOrderPresentation(authorizedFetch, request.signal)
      .then((value) => {
        if (active && !request.signal.aborted) setRead({ owner: authorizedFetch, retry, value, failed: false });
      })
      .catch(() => {
        if (active && !request.signal.aborted) setRead({ owner: authorizedFetch, retry, value: null, failed: true });
      });
    return () => { active = false; request.abort(); };
  }, [authorizedFetch, retry]);

  // Hide prior-source and prior-attempt state before the next effect runs.
  const current = read?.owner === authorizedFetch && read.retry === retry ? read : null;
  const data = current?.value ?? null;
  const error = current?.failed ?? false;

  useEffect(() => {
    if (error && progress.current?.ownerDocument.activeElement === progress.current) retryButton.current?.focus();
  }, [error]);

  return (
    <div>
      <p ref={progress} role="status" tabIndex={-1}>
        {error ? "" : data ? "Command center loaded." : "Loading command center…"}
      </p>
      {error && <div role="alert">
      <p>The command center could not be loaded.</p>
      <button ref={retryButton} type="button" onClick={(event) => {
        if (event.currentTarget.ownerDocument.activeElement === event.currentTarget) progress.current?.focus();
        setRetry((value) => value + 1);
      }}>Retry command center</button>
      </div>}
      {data && <main>
      <h1>Work order command center</h1>

      <dl aria-label={data.metrics.title ?? "Metrics"}>
        {data.metrics.items.map((metric) => (
          <div key={metric.key}><dt>{metric.label}</dt><dd>{metric.value}</dd></div>
        ))}
      </dl>

      <section aria-labelledby="status-heading">
        <h2 id="status-heading">{data.byStatus.title}</h2>
        {data.byStatus.items.map((item) => (
          <p key={item.key}>
            {item.label}: <progress value={item.value} max={item.maximum} /> {item.displayValue}
          </p>
        ))}
      </section>

      <section aria-labelledby="recent-heading">
        <h2 id="recent-heading">{data.recent.title}</h2>
        <ul>{data.recent.items.map((item) => (
          <li key={item.id} data-record-id={item.recordId}>
            <strong>{item.primary}</strong>{item.secondary && <> — {item.secondary}</>}
            {item.status && <span> · {item.status.label}</span>}
          </li>
        ))}</ul>
      </section>

      <table>
        <caption>{data.table.title}</caption>
        <thead><tr>{data.table.columns.map((column) => <th key={column.key}>{column.label}</th>)}</tr></thead>
        <tbody>{data.table.rows.map((row) => (
          <tr key={row.id}>{data.table.columns.map((column) => {
            const cell = row.cells[column.key];
            const text = typeof cell === "object" && cell !== null ? cell.label : String(cell ?? "");
            return <td key={column.key}>{text}</td>;
          })}</tr>
        ))}</tbody>
      </table>

      <ol aria-label={data.timeline.title}>{data.timeline.items.map((item) => (
        <li key={item.id}><time dateTime={item.occurredUtc}>{item.occurredUtc}</time> {item.title}</li>
      ))}</ol>
      </main>}
    </div>
  );
}
```

Tip

For ThemeForest-level visual quality, keep this data contract stable and invest in typography, spacing rhythm, responsive grid composition, empty/loading skeletons, restrained motion, branded chart palettes, dense-versus-comfortable modes and excellent record-detail transitions. Theme tokens can change the look without changing the API or security model.

## Give another module the same presentation capability

Do not force every endpoint to manufacture all six shapes. Keep natural list/detail/write endpoints, then add one purpose-built presentation binding per meaningful screen. A Contacts overview might return metrics, lifecycle distribution and recent contacts; a Files page might return storage metrics, MIME distribution and recent uploads; Universal Inbox might return queue metrics, status progress, recent items and a timeline.

```
1. Pick a screen use-case, not a table: for example, "work-order command center".
2. Define one or more presentationVersion 1 children using only the six normalized shapes.
3. Implement a reviewed, bounded, secured server contract. Apply tenant, active-user,
   DataRole, Location, soft-delete and record-specific fences before aggregation.
4. Register a DataConnector and DataBinding. The binding key is public vocabulary;
   physical server and database names are routing details and never appear in page JSON.
5. Add registry manifests for the blocks the page uses; do not add renderer-specific scripts.
6. Compose the Page in Puck. Reuse one bindingKey and select children with dataKey.
7. Test exact/empty/maximum cardinality, forbidden and cross-tenant requests, stale sessions,
   per-item batch failures, keyboard access, mobile overflow, and real browser rendering.
8. Rehearse on a disposable SaaS triple, apply to the golden SaaS DB, re-export it,
   regenerate contracts/knowledge, and prove live/export parity before release.
```

Important

A page binding is not authorization. The reviewed server contract must derive SaaS app, account and user from verified identity and enforce DataRoles, Locations, soft delete, direct/private record fences and module permissions before it counts, groups or returns anything.

## Loading, errors, pagination and performance

- A page may request 1–24 unique binding keys. Duplicate keys are rejected by the client parser; the native renderer deduplicates them before requesting.
- The server resolves at most four bindings concurrently and returns `Cache-Control: private, no-store`. Connector-specific short caching is server controlled.
- Empty collections are `[]`, never `null`. An empty tenant still renders a valid zero/empty presentation.
- The grid sorts only the already-authorized visible page. Search, filtering and deep pagination stay server-side.
- Return only display-ready fields needed by the blocks. Do not fetch a million rows, serialize them, and reduce them in React.
- Presentation status and tone are display metadata only. They never grant permission or prove workflow state.
- Use separate bindings when panels have different refresh rates or failure boundaries; use one composed binding when they share scope, cache lifetime and screen intent.

## Release verification

```
npm --prefix apps\tenant-runtime test -- src\PresentationContracts.test.ts src\ProfessionalPrimitives.test.tsx src\PageRenderer.test.tsx src\api.test.ts src\PuckPageDesignerAdapter.test.ts
npm --prefix apps\tenant-runtime run build

# Database reconciliation is rehearsal-only unless --apply is supplied.
python tools\reconcile_work_order_presentations.py --help

# Run the real authenticated journey with credentials supplied through environment variables.
tests\e2e\node_modules\.bin\playwright.cmd test --config tests\e2e\interactive-presentations-live.config.ts
```

The retained Work Orders example was exercised through real tenant login, SQL routing, the API batch, the production React build and Chromium. The observed result was one binding request, 4 metrics, 6 status rows, 6 recent rows, 3 chart periods, 6 grid rows and 6 timeline events; desktop content was 1,010px wide, mobile overflow was zero, and no authenticated API, page, console or accessible-name failure occurred. That is functional evidence, not a production capacity claim.

Continue with the [Professional Template Foundation](professional-template-foundation.html), [headless application kit](headless-application-kit.html), and [complete component catalog](react-component-catalog.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/interactive-api-presentations.html).

---
title: "Headless application guide and copy/paste kit"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/headless-application-kit.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Headless application guide and copy/paste kit

Build a custom frontend over BuildWithHQ authentication, scoped APIs, first-class modules, Inbox, Workflow, Files and exact server-side authorization.

## In brief

- **Capabilities:** 25
- **Page routes:** 304
- **Additional routes:** 115

A headless BuildWithHQ application replaces the native page presentation with your own React, Vue, mobile, desktop, or server-rendered interface. It does **not** replace authentication, tenant routing, DataRoles, Locations, stored-procedure contracts, audit, rate limits, files, Workflow, Inbox, or AI authorization.

[Choose the boundary](#boundary) [Transport](#transport) [Working example](#contacts-example) [Inbox & tickets](#headless-inbox) [Menus & shell](#headless-menu) [All capabilities](#headless-all) [Test checklist](#headless-tests)

Note

This guide is generated from the same catalog as the native React kit: 25 capabilities, 304 page-module routes, and 115 additional tenant/Design routes. It does not invent a second backend.

## 1. Choose the correct headless boundary

| Caller | Use | Do not do |
| --- | --- | --- |
| **Custom tenant browser UI** | The current same-origin tenant session plus the typed tenant APIs cataloged below. | Do not store the access token in localStorage or submit tenant/database identity as authorization. |
| **External server or integration** | The published Developer Platform, app-bound credentials, generated OpenAPI and versioned gateway routes. Exchange an external subject for a short-lived delegated-user token when a browser must call modules directly. | Do not place the long-lived `bwk_live_` app key in browser/mobile bundles or call internal tenant routes as an unauthenticated proxy. |
| **Custom appliance service** | A declared installed-service endpoint with reviewed egress, secret references, action permissions and correlation. | Do not expose provider credentials, unrestricted SQL or tenant infrastructure to the frontend. |

Important

The generated transport below intentionally accepts only same-origin /api/ paths. If the frontend runs on another origin, use the published Developer API contract and its supported authentication/CORS boundary; do not weaken this check.

## External identity and delegated-user tokens

The Developer API can create AppAccounts and passwordless TenantUsers, assign DataRoles and Locations, and exchange the ISV's authenticated external subject for a 2–15 minute `bwu_live_` token. The app key remains on the trusted server. The delegated token carries no database route or caller-supplied authorization, cannot manage identities, and is rechecked against the current parent grant and active TenantUser on use.

Use `tenant-accounts.read/write`, `tenant-users.read/write`, and `tenant-users.tokens.issue` only on the trusted server. Use module read/write scopes on the short token. Revocation is immediate, and deactivating a user revokes all active tokens for that app/account/user.

## 2. Copy the same-origin transport

The transport adds the current in-memory bearer token, delegates unsafe-method CSRF handling to the existing security helper, assigns a correlation ID, preserves server-side status/code/error/correlation details, clears local session state on 401, and never accepts a database name.

```

export type HeadlessMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";

export interface HeadlessRequest {
  readonly method?: HeadlessMethod;
  readonly body?: unknown;
  readonly signal?: AbortSignal;
  readonly headers?: Readonly<Record<string, string>>;
}

export interface HeadlessTransportOptions {
  readonly accessToken: () => string | null | undefined;
  readonly fetchImplementation?: typeof fetch;
  readonly applyCsrfHeader?: (headers: Headers, method: string) => void;
  readonly onUnauthorized?: () => void;
}

export interface HeadlessTransport {
  request<T>(path: string, request?: HeadlessRequest): Promise<T>;
}

export class HeadlessApiError extends Error {
  public constructor(
    message: string,
    public readonly status: number,
    public readonly code: string,
    public readonly correlationId?: string,
    public readonly retryAfterSeconds?: number,
  ) { super(message); this.name = "HeadlessApiError"; }
}

const sameOriginApiPath = (path: string): string => {
  if (!path.startsWith("/api/") || path.includes("://") || path.includes("#") || path.length > 4000 || /[\u0000-\u0020\u007f\\]/.test(path)) {
    throw new TypeError("Headless tenant requests require a bounded same-origin /api/ path.");
  }
  let pathname: string;
  try { pathname = decodeURIComponent(path.split("?", 1)[0]); } catch { throw new TypeError("The API path is invalid."); }
  if (pathname.includes("\\") || pathname.split("/").some(segment => segment === "." || segment === "..") || /%(?:25|2e|2f|5c)/i.test(pathname) || !new URL(path, "https://bwhq.invalid").pathname.startsWith("/api/")) {
    throw new TypeError("Headless tenant requests require a bounded same-origin /api/ path.");
  }
  return path;
};

const readProblem = async (response: Response): Promise<HeadlessApiError> => {
  let body: Record<string, unknown> = {};
  try { const value: unknown = await response.json(); if (value && typeof value === "object" && !Array.isArray(value)) body = value as Record<string, unknown>; } catch { /* safe fallback below */ }
  const validDelay = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
  const header = response.headers.get("Retry-After");
  const retryHeader = header !== null && /^\d+$/.test(header.trim()) ? Number(header) : undefined;
  const retryAfterSeconds = validDelay(body.retryAfterSeconds) ? body.retryAfterSeconds : validDelay(retryHeader) ? retryHeader : undefined;
  return new HeadlessApiError(
    typeof body.error === "string" ? body.error : `Request failed (${response.status}).`,
    response.status,
    typeof body.code === "string" ? body.code : "request_failed",
    typeof body.correlationId === "string" ? body.correlationId : response.headers.get("X-Correlation-ID") ?? undefined,
    retryAfterSeconds,
  );
};

export const createSameOriginHeadlessTransport = (options: HeadlessTransportOptions): HeadlessTransport => {
  const fetchImplementation = options.fetchImplementation ?? globalThis.fetch;
  if (!fetchImplementation) throw new TypeError("A fetch implementation is required.");
  return {
    async request<T>(path: string, request: HeadlessRequest = {}): Promise<T> {
      const method = request.method ?? "GET";
      const headers = new Headers({ Accept: "application/json", ...request.headers });
      const token = options.accessToken();
      if (!token) { options.onUnauthorized?.(); throw new HeadlessApiError("Sign in before loading tenant data.", 401, "tenant_session_required"); }
      headers.set("Authorization", `Bearer ${token}`);
      headers.set("X-Correlation-ID", crypto.randomUUID());
      if (request.body !== undefined) headers.set("Content-Type", "application/json");
      options.applyCsrfHeader?.(headers, method);
      const response = await fetchImplementation(sameOriginApiPath(path), {
        method,
        credentials: "same-origin",
        redirect: "error",
        headers,
        body: request.body === undefined ? undefined : JSON.stringify(request.body),
        signal: request.signal,
      });
      if (response.status === 401) options.onUnauthorized?.();
      if (!response.ok) throw await readProblem(response);
      if (response.status === 204) return undefined as T;
      return await response.json() as T;
    },
  };
};

/* In apps/tenant-runtime, inject getTenantAccessToken, applyCsrfHeader and
   clearTenantSession. Keep refresh/session rotation in the official auth client. */
```

### Wire it to the official tenant session

```
import { clearTenantSession, getTenantAccessToken } from "./api";
import { applyCsrfHeader } from "./webSecurity";
import { createSameOriginHeadlessTransport } from "./HeadlessTransport";

export const transport = createSameOriginHeadlessTransport({
  accessToken: getTenantAccessToken,
  applyCsrfHeader,
  onUnauthorized: clearTenantSession,
});

// Keep login, refresh rotation, logout and session restore in the official
// tenant auth client. The custom component consumes only this transport.
```

Let the existing login/refresh client own refresh-cookie rotation and session restore. A 401 should return the app to its sign-in state; a 403 is an authorization denial, 404 keeps absent and foreign identifiers indistinguishable, 409 requires reloading stale state, and 429 requires honoring the retry window.

## 3. Working, paginated read/write example

This example requests exactly one 25-row page from `/api/modules/contacts`, parses the response through `parseContactList`, creates through the reviewed POST contract, validates the receipt with `parseContactMutation`, aborts obsolete reads, and never fetches a full table to filter in React.

```

import { useEffect, useRef, useState, type CSSProperties, type FormEvent } from "react";
import { contactsModule, parseContactList, parseContactMutation, type ContactList, type ContactWrite } from "@buildwithhq/module-sdk";
import type { HeadlessTransport } from "./HeadlessTransport";

interface ScopeChoices {
  readonly items: readonly { readonly dataRoleId: number; readonly roleName: string }[];
  readonly locations: readonly { readonly locationId: string; readonly locationName: string }[];
  readonly locationRequired: boolean;
  readonly canChooseAllLocations: boolean;
}

const unavailableChoices = () => new Error("Record-scope choices are unavailable. Refresh visibility before creating a contact.");
const object = (value: unknown): Record<string, unknown> => {
  if (!value || typeof value !== "object" || Array.isArray(value)) throw unavailableChoices();
  return value as Record<string, unknown>;
};
const guid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
const named = (value: unknown): value is string => typeof value === "string" && value.trim().length > 0;

// Same contract as the native shared record-scope picker; the server remains
// authoritative for the selected scope when the contact is committed.
export const parseHeadlessContactScopeChoices = (value: unknown): ScopeChoices => {
  const root = object(value);
  if (root.contractVersion !== 1 || !Array.isArray(root.items) || !Array.isArray(root.locations) ||
      typeof root.locationRequired !== "boolean" || typeof root.canChooseAllLocations !== "boolean") throw unavailableChoices();
  const roles = new Set<number>(), locations = new Set<string>();
  const items = root.items.map((entry) => {
    const item = object(entry), id = item.dataRoleId;
    if (typeof id !== "number" || !Number.isInteger(id) || id <= 0 || id > 2147483647 || roles.has(id) || !named(item.roleName)) throw unavailableChoices();
    roles.add(id);
    return { dataRoleId: id, roleName: item.roleName };
  });
  const availableLocations = root.locations.map((entry) => {
    const item = object(entry), id = item.locationId;
    if (typeof id !== "string" || !guid.test(id) || /^0{8}-0{4}-0{4}-0{4}-0{12}$/.test(id) ||
        locations.has(id.toLowerCase()) || !named(item.locationName)) throw unavailableChoices();
    locations.add(id.toLowerCase());
    return { locationId: id, locationName: item.locationName };
  });
  if (availableLocations.length && !root.locationRequired) throw unavailableChoices();
  return { items, locations: availableLocations, locationRequired: root.locationRequired, canChooseAllLocations: root.canChooseAllLocations };
};

type CreateScope = Pick<ContactWrite, "dataRoleId" | "locationId" | "locationScope"> & { readonly isPersonal: boolean };
export const readHeadlessContactCreateScope = (choices: ScopeChoices | undefined, visibility: string, location: string): CreateScope => {
  if (!choices) throw unavailableChoices();
  if (visibility === "personal") return { isPersonal: true };
  const match = /^role:([1-9][0-9]*)$/.exec(visibility), role = match && Number(match[1]);
  if (!role || !choices.items.some((item) => item.dataRoleId === role)) throw new Error("Choose Personal or an available DataRole.");
  if (!choices.locationRequired) {
    if (location) throw new Error("Refresh visibility before selecting a location.");
    return { isPersonal: false, dataRoleId: role };
  }
  if (location === "all" && choices.canChooseAllLocations) return { isPersonal: false, dataRoleId: role, locationScope: "All" };
  const selected = choices.locations.find((item) => item.locationId.toLowerCase() === location.toLowerCase());
  if (!selected) throw new Error("Choose an available location or an authorized All locations option.");
  return { isPersonal: false, dataRoleId: role, locationScope: "Specific", locationId: selected.locationId };
};

export interface HeadlessContactsExampleProps {
  readonly transport: HeadlessTransport;
  readonly styled?: boolean;
}

export const HeadlessContactsExample = ({ transport, styled = false }: HeadlessContactsExampleProps) => {
  const [page, setPage] = useState(1), [search, setSearch] = useState("");
  const [result, setResult] = useState<ContactList>(), [readError, setReadError] = useState<string>();
  const [refresh, setRefresh] = useState(0), [scopeRefresh, setScopeRefresh] = useState(0);
  const [choices, setChoices] = useState<ScopeChoices>(), [scopeError, setScopeError] = useState<string>();
  const [visibility, setVisibility] = useState(""), [location, setLocation] = useState("");
  const [firstName, setFirstName] = useState(""), [lastName, setLastName] = useState(""), [email, setEmail] = useState("");
  const [createError, setCreateError] = useState<string>(), [created, setCreated] = useState(false), [creating, setCreating] = useState(false);
  const inFlight = useRef(false);

  useEffect(() => {
    const controller = new AbortController(); let active = true;
    const query = new URLSearchParams({ pageNumber: String(page), pageSize: "25" });
    if (search.trim()) query.set("search", search.trim());
    setResult(undefined); setReadError(undefined);
    void transport.request<unknown>(`${contactsModule.apiBasePath}?${query}`, { signal: controller.signal })
      .then((value) => { if (active && !controller.signal.aborted) setResult(parseContactList(value)); })
      .catch((failure: unknown) => { if (active && !controller.signal.aborted) setReadError(failure instanceof Error ? failure.message : "Contacts unavailable."); });
    return () => { active = false; controller.abort(); };
  }, [page, refresh, search, transport]);

  useEffect(() => {
    const controller = new AbortController(); let active = true;
    setChoices(undefined); setScopeError(undefined); setVisibility(""); setLocation("");
    void transport.request<unknown>("/api/runtime/record-scope/create-roles", { signal: controller.signal })
      .then((value) => { if (active && !controller.signal.aborted) setChoices(parseHeadlessContactScopeChoices(value)); })
      .catch((failure: unknown) => { if (active && !controller.signal.aborted) setScopeError(failure instanceof Error ? failure.message : "Record-scope choices unavailable."); });
    return () => { active = false; controller.abort(); };
  }, [scopeRefresh, transport]);

  const create = async (event: FormEvent<HTMLFormElement>) => {
    event.preventDefault(); if (inFlight.current) return;
    setCreateError(undefined); setCreated(false);
    try {
      const scope = readHeadlessContactCreateScope(choices, visibility, location);
      if (![firstName, lastName, email].some((value) => value.trim())) throw new Error("Enter a name or email for the contact.");
      const body: ContactWrite = { firstName, lastName, email, ...scope };
      inFlight.current = true; setCreating(true);
      const value = await transport.request<unknown>(contactsModule.apiBasePath, { method: "POST", body });
      parseContactMutation(value);
      setFirstName(""); setLastName(""); setEmail(""); setVisibility(""); setLocation("");
      setCreated(true); setPage(1); setRefresh((value) => value + 1);
    } catch (failure) { setCreateError(failure instanceof Error ? failure.message : "Contact creation could not be confirmed. Refresh the list before retrying."); }
    finally { inFlight.current = false; setCreating(false); }
  };

  const shared = visibility.startsWith("role:");
  const locationUnavailable = shared && !!choices?.locationRequired && !choices.locations.length && !choices.canChooseAllLocations;
  const submitDisabled = !choices || !!scopeError || locationUnavailable || creating;
  const controlStyle: CSSProperties | undefined = styled ? { boxSizing: "border-box", minWidth: 0, width: "100%",
    border: "1px solid var(--catalog-border, #dce2ea)", borderRadius: 7, font: "inherit", padding: "8px 10px" } : undefined;
  const buttonStyle = (disabled = false, primary = false): CSSProperties | undefined => styled ? {
    background: primary ? "var(--catalog-accent, #3659e3)" : "transparent", border: "1px solid var(--catalog-border, #dce2ea)",
    borderColor: primary ? "var(--catalog-accent, #3659e3)" : undefined, borderRadius: 7,
    color: primary ? "white" : "var(--catalog-ink, #172033)", cursor: disabled ? "not-allowed" : "pointer",
    font: "inherit", fontWeight: primary ? 600 : undefined, minHeight: 38, opacity: disabled ? .5 : 1, padding: "8px 12px",
  } : undefined;
  return <section className={styled ? "bwhq-headless-resource" : undefined}>
    <header><div><p>Headless first-class module</p><h2>Contacts</h2></div>
      <label>Search visible contacts<input style={controlStyle} type="search" value={search} onChange={(event) => { setSearch(event.target.value); setPage(1); }} /></label>
      <button style={buttonStyle()} type="button" onClick={() => setRefresh((value) => value + 1)}>Refresh contacts</button>
    </header>
    {readError && <p role="alert">{readError}</p>}
    {!result && !readError && <p role="status">Loading contacts…</p>}
    {result && <>{result.items.length === 0 ? <p role="status">No contacts match this view.</p> :
      <ul>{result.items.map((contact) => <li key={contact.recordId}><strong>{contact.title}</strong><span>{contact.email || contact.companyName || "No secondary value"}</span></li>)}</ul>}
      <nav aria-label="Contact pages"><button style={buttonStyle(page <= 1)} disabled={page <= 1} onClick={() => setPage((value) => value - 1)} type="button">Previous</button>
        <span>Page {result.pageNumber} of {Math.max(1, result.totalPages)}</span>
        <button style={buttonStyle(page >= result.totalPages)} disabled={page >= result.totalPages} onClick={() => setPage((value) => value + 1)} type="button">Next</button></nav></>}
    <form onSubmit={(event) => void create(event)}><h3>Create a contact</h3>
      {createError && <p role="alert">{createError}</p>}{created && <p role="status">Contact created.</p>}
      <fieldset disabled={creating} style={styled ? { border: 0, display: "grid", gap: 14,
        gridTemplateColumns: "repeat(auto-fit, minmax(min(100%, 360px), 1fr))", margin: 0, minWidth: 0, padding: 0 } : undefined}>
        <legend style={styled ? { color: "var(--catalog-muted, #637087)", marginBottom: 12, padding: 0 } : undefined}>Contact details and visibility</legend>
        <label>First name<input style={controlStyle} maxLength={100} value={firstName} onChange={(event) => setFirstName(event.target.value)} /></label>
        <label>Last name<input style={controlStyle} maxLength={100} value={lastName} onChange={(event) => setLastName(event.target.value)} /></label>
        <label style={styled ? { gridColumn: "1 / -1" } : undefined}>Email<input style={controlStyle} type="email" maxLength={320} value={email} onChange={(event) => setEmail(event.target.value)} /></label>
        <label>Visibility (required)<select style={controlStyle} aria-label="Visibility" required disabled={!choices || !!scopeError} value={visibility}
          onChange={(event) => { setVisibility(event.target.value); setLocation(""); }}>
          <option value="">{choices ? "Choose visibility" : "Loading visibility…"}</option>
          {choices && <option value="personal">Personal</option>}
          {choices?.items.map((role) => <option key={role.dataRoleId} value={`role:${role.dataRoleId}`}>{role.roleName}</option>)}
        </select></label>
        {shared && choices?.locationRequired && <label>Record location (required)<select style={controlStyle} aria-label="Record location" required value={location}
          disabled={locationUnavailable} onChange={(event) => setLocation(event.target.value)}>
          <option value="">Choose a location</option>
          {choices.canChooseAllLocations && <option value="all">All locations</option>}
          {choices.locations.map((item) => <option key={item.locationId} value={item.locationId}>{item.locationName}</option>)}
        </select></label>}
        {scopeError && <p role="alert">{scopeError}</p>}
        {choices && !choices.items.length && <p role="status">Shared records are unavailable; choose Personal to create a private contact.</p>}
        {locationUnavailable && <p role="status">No shared location is available. Refresh visibility or choose Personal.</p>}
        <div style={styled ? { display: "flex", flexWrap: "wrap", gap: 10, gridColumn: "1 / -1", justifyContent: "flex-end" } : undefined}>
          <button style={buttonStyle(creating)} type="button" onClick={() => setScopeRefresh((value) => value + 1)}>Refresh visibility</button>
          <button style={buttonStyle(submitDisabled, true)} type="submit" disabled={submitDisabled}>{creating ? "Creating…" : "Create contact"}</button>
        </div>
      </fieldset>
    </form>
  </section>;
};
```

### Use it

```
import { HeadlessContactsExample } from "./HeadlessContactsExample";
import { transport } from "./transport";

export const ContactsPage = () => (
  <HeadlessContactsExample transport={transport} styled />
);
```

Tip

Copy the pattern, not the Contacts field names: bounded query parameters, unknown JSON at the transport boundary, official SDK parser, server pagination, explicit loading/empty/error states, and one narrow mutation receipt.

## 4. Headless data bindings

For custom page-shaped projections, request a reviewed binding key. The server resolves it to an approved `sp_ds_*` contract and applies the signed-in identity. The client does not send SQL, a procedure name, a SaaS ID, or a database selector.

```
import { parseRuntimeDataBinding } from "@buildwithhq/page-runtime";
import { transport } from "./transport";

export const loadOpenWork = async (signal: AbortSignal) => {
  const bindingKey = "work.open";
  const raw = await transport.request<unknown>(
    `/api/runtime/data/${encodeURIComponent(bindingKey)}`,
    { signal },
  );
  return parseRuntimeDataBinding(raw, bindingKey).data;
};
```

### Embed a published page from an external application

Developer Kit 1.16.0 adds `BuildWithHQRuntimeClient` for a short-lived `bwu_live_` token. `getPageBody` returns `components + page` without menus or shell; `getPageBootstrap` returns the complete `shell + components + page`. Body reads omit page design tokens by default so the host theme wins.

Grant `runtime.pages.read` for either page read and `runtime.bindings.read` for `resolveBindings`. The batch accepts 1-24 unique keys. These public routes reuse the native page resolution, entitlement fallback, binding procedures, DataRole/Location filters, record authorization, tenant routing, and page audit.

## 5. Universal Inbox, support tickets and GoClaw

The official package exposes typed clients independently from its native UI. A headless component can consume those clients for bounded queues, ticket-only views, badge/notifications, email ticketing settings, human state, Workflow decisions and GoClaw review work. Use the native components when you want the complete lifecycle without reimplementing every control.

```
import {
  createApprovalQueueHttpClient,
  createUniversalInboxHttpClient,
} from "@buildwithhq/universal-inbox";
import { ensureCsrfToken } from "./webSecurity";
import { getTenantAccessToken } from "./api";
import {
  HeadlessApprovalQueueStarter,
  HeadlessInboxQueueStarter,
} from "./UniversalInboxStarters";

const inboxClient = createUniversalInboxHttpClient({
  accessToken: getTenantAccessToken,
  csrfToken: ensureCsrfToken,
});
const approvalClient = createApprovalQueueHttpClient({
  accessToken: getTenantAccessToken,
  csrfToken: ensureCsrfToken,
});

export const SupportQueue = () => (
  <HeadlessInboxQueueStarter client={inboxClient} ticketingOnly styled />
);
export const AiReviewQueue = () => (
  <HeadlessApprovalQueueStarter client={approvalClient} styled />
);
```

**Copy all native and headless Inbox/GoClaw starters**

```

import { useEffect, useState } from "react";

export interface InboxQueueItem {
  readonly inboxItemId: string;
  readonly source: { readonly sourceType: string };
  readonly subject?: string | null;
  readonly previewText?: string | null;
  readonly status: string;
  readonly ticket?: { readonly key?: string | null } | null;
}
export interface UniversalInboxClient {
  list(request: { readonly ticketingOnly?: boolean; readonly assignedToMe?: boolean; readonly topN: number }, signal?: AbortSignal): Promise<readonly InboxQueueItem[]>;
}
export interface ApprovalQueueItem {
  readonly suggestionBatchId: string;
  readonly subject?: string | null;
  readonly summary?: string | null;
  readonly sourceType?: string | null;
  readonly batchStatus: string;
  readonly isStale: boolean;
}
export interface ApprovalQueueClient {
  list(top: number, signal?: AbortSignal): Promise<readonly ApprovalQueueItem[]>;
}

interface InboxStarterProps {
  readonly client: UniversalInboxClient;
  readonly ticketingOnly?: boolean;
  readonly assignedToMe?: boolean;
  readonly onOpen?: (inboxItemId: string) => void;
  readonly styled?: boolean;
}

export const HeadlessInboxQueueStarter = ({ client, ticketingOnly, assignedToMe, onOpen, styled = false }: InboxStarterProps) => {
  const [items, setItems] = useState<readonly InboxQueueItem[]>([]);
  const [error, setError] = useState<string>();
  const [loading, setLoading] = useState(true);
  useEffect(() => {
    const controller = new AbortController();
    setLoading(true); setError(undefined);
    void client.list({ ticketingOnly, assignedToMe, topN: 100 }, controller.signal)
      .then(setItems)
      .catch((failure: unknown) => { if (!controller.signal.aborted) setError(failure instanceof Error ? failure.message : "Inbox unavailable."); })
      .finally(() => { if (!controller.signal.aborted) setLoading(false); });
    return () => controller.abort();
  }, [assignedToMe, client, ticketingOnly]);
  return <section aria-busy={loading} className={styled ? "bwhq-headless-list" : undefined}>
    <h2>{ticketingOnly ? "Support tickets" : "Universal Inbox"}</h2>
    {loading && <p role="status">Loading inbox…</p>}
    {error && <p role="alert">{error}</p>}
    {!loading && !error && items.length === 0 && <p>No visible work.</p>}
    <ul>{items.map((item) => <li key={item.inboxItemId}><button type="button" onClick={() => onOpen?.(item.inboxItemId)}><strong>{item.ticket?.key ? item.ticket.key + " · " : ""}{item.subject || item.source.sourceType}</strong><span>{item.status} · {item.previewText || "No preview"}</span></button></li>)}</ul>
  </section>;
};

interface ApprovalStarterProps {
  readonly client: ApprovalQueueClient;
  readonly onOpen?: (item: ApprovalQueueItem) => void;
  readonly styled?: boolean;
}

export const HeadlessApprovalQueueStarter = ({ client, onOpen, styled = false }: ApprovalStarterProps) => {
  const [items, setItems] = useState<readonly ApprovalQueueItem[]>([]);
  const [error, setError] = useState<string>();
  useEffect(() => {
    const controller = new AbortController();
    void client.list(100, controller.signal).then(setItems)
      .catch((failure: unknown) => { if (!controller.signal.aborted) setError(failure instanceof Error ? failure.message : "Approval queue unavailable."); });
    return () => controller.abort();
  }, [client]);
  return <section className={styled ? "bwhq-headless-list" : undefined}>
    <h2>GoClaw approval work</h2>{error && <p role="alert">{error}</p>}
    <ul>{items.map((item) => <li key={item.suggestionBatchId}><button type="button" onClick={() => onOpen?.(item)}><strong>{item.subject || item.summary || item.sourceType}</strong><span>{item.batchStatus}{item.isStale ? " · stale" : ""}</span></button></li>)}</ul>
  </section>;
};

/* Self-contained starter aliases: no unpublished product package is required. */
export const BareNativeUniversalInbox = (props: { readonly client: UniversalInboxClient; readonly initialInboxItemId?: string }) =>
  <HeadlessInboxQueueStarter client={props.client} />;
export const FramedNativeUniversalInbox = (props: { readonly client: UniversalInboxClient; readonly initialInboxItemId?: string }) =>
  <div className="bwhq-native-frame"><HeadlessInboxQueueStarter client={props.client} styled /></div>;
export const BareNativeGoClawApprovalQueue = (props: { readonly client: ApprovalQueueClient }) =>
  <HeadlessApprovalQueueStarter client={props.client} />;
export const FramedNativeGoClawApprovalQueue = (props: { readonly client: ApprovalQueueClient }) =>
  <div className="bwhq-native-frame"><HeadlessApprovalQueueStarter client={props.client} styled /></div>;
```

Important

The headless list starters demonstrate reads and selection. They do not silently implement ticket resolution, proof/file handling, Workflow approval, GoClaw edits or delivery retry. Call the corresponding typed client method only from an explicit UI action and preserve ActivityVersion/stale-state inputs.

## 6. Menus and the custom workspace shell

Use the server-returned User Type menu for navigation and presentation. An entitled published page may also be opened directly when it is absent from the menu. Neither a menu entry nor page access grants record or action permission; each request still checks the signed-in user's current Personal, DataRole and location authority. The current shell starter stays left aligned and expands the center while allowing an optional 280px context panel.

```
import { BuildWithHQMenu } from "./BuildWithHQMenu";
import { StyledTenantWorkspaceShell } from "./TenantWorkspaceShell";

export const AppShell = ({ menu, pageKey, children }) => (
  <StyledTenantWorkspaceShell
    applicationName="Your SaaS"
    pageTitle="Workspace"
    menu={<BuildWithHQMenu
      items={menu}
      activePageKey={pageKey}
      resolvePageHref={(key) => `/?page=${encodeURIComponent(key)}`}
      styled
    />}
    contextPanel={<p>Page-specific context belongs here.</p>}
  >
    {children}
  </StyledTenantWorkspaceShell>
);
```

**Copy the complete menu component**

```

import type { ReactNode } from "react";

export interface BuildWithHQMenuItem {
  readonly id: string;
  readonly parentId?: string | null;
  readonly label: string;
  readonly iconKey?: string | null;
  readonly targetType: "Page" | "Group" | "Module" | "External";
  readonly pageKey?: string | null;
  readonly url?: string | null;
  readonly sortOrder: number;
}

export interface BuildWithHQMenuProps {
  readonly items: readonly BuildWithHQMenuItem[];
  readonly activePageKey?: string;
  readonly resolvePageHref: (pageKey: string) => string;
  readonly icon?: (iconKey: string) => ReactNode;
  readonly styled?: boolean;
}

const safeExternalUrl = (value: string | null | undefined): string | undefined => {
  if (!value || value.length > 2000) return undefined;
  try {
    const url = new URL(value);
    return url.protocol === "https:" && !url.username && !url.password ? url.toString() : undefined;
  } catch { return undefined; }
};

export const BuildWithHQMenu = ({ items, activePageKey, resolvePageHref, icon, styled = false }: BuildWithHQMenuProps) => {
  const roots = items.filter((item) => !item.parentId).sort((left, right) => left.sortOrder - right.sortOrder);
  const renderItem = (item: BuildWithHQMenuItem): ReactNode => {
    const children = items.filter((candidate) => candidate.parentId === item.id).sort((left, right) => left.sortOrder - right.sortOrder);
    if (item.targetType === "Group") return <li key={item.id}><span>{item.iconKey && icon?.(item.iconKey)}{item.label}</span>{children.length > 0 && <ul>{children.map(renderItem)}</ul>}</li>;
    const href = item.targetType === "Page" && item.pageKey ? resolvePageHref(item.pageKey)
      : item.targetType === "External" ? safeExternalUrl(item.url) : undefined;
    return <li key={item.id}>{href ? <a href={href} aria-current={item.pageKey === activePageKey ? "page" : undefined}>{item.iconKey && icon?.(item.iconKey)}{item.label}</a> : <span aria-disabled="true">{item.label}</span>}</li>;
  };
  return <nav aria-label="Application" className={styled ? "bwhq-app-menu" : undefined}><ul>{roots.map(renderItem)}</ul></nav>;
};
```

**Copy the complete workspace shell**

```

import type { ReactNode } from "react";

export interface TenantWorkspaceShellProps {
  readonly applicationName: string;
  readonly pageTitle: string;
  readonly menu: ReactNode;
  readonly children: ReactNode;
  readonly headerActions?: ReactNode;
  readonly contextPanel?: ReactNode;
  readonly styled?: boolean;
}

const TenantWorkspaceShellBody = ({ applicationName, pageTitle, menu, children, headerActions, contextPanel, styled = false }: TenantWorkspaceShellProps) => (
  <div className={styled ? "bwhq-workspace" : undefined}>
    <header className={styled ? "bwhq-workspace__header" : undefined}>
      <div><p>{applicationName}</p><h1>{pageTitle}</h1></div>
      {headerActions && <div aria-label="Page actions">{headerActions}</div>}
    </header>
    <div className={styled ? "bwhq-workspace__columns" : undefined}>
      <aside aria-label="Application menu" className={styled ? "bwhq-workspace__menu" : undefined}>{menu}</aside>
      <main className={styled ? "bwhq-workspace__main" : undefined}>{children}</main>
      {contextPanel && <aside aria-label="Page context" className={styled ? "bwhq-workspace__context" : undefined}>{contextPanel}</aside>}
    </div>
  </div>
);

export const UnstyledTenantWorkspaceShell = (props: Omit<TenantWorkspaceShellProps, "styled">) =>
  <TenantWorkspaceShellBody {...props} styled={false} />;

export const StyledTenantWorkspaceShell = (props: Omit<TenantWorkspaceShellProps, "styled">) =>
  <TenantWorkspaceShellBody {...props} styled />;
```

## 7. Files and binary responses

`HeadlessTransport` is intentionally JSON-only. For multipart upload and Blob download, reuse the current typed `uploadFile`, `downloadFileContent`, `uploadTenantAsset`, and `loadTenantAssetContent` functions or implement their exact reviewed contracts. Keep MIME/size validation, CSRF, unauthorized-download denial, malware scanning state, orphan cleanup and native File authorization intact.

## 8. Every capability and exact operation

Each section lists the current integration kind, page key where one exists, API roots, public package-client methods, exact HTTP routes, current browser function and response parser. A background capability with no interactive route is explicitly left without one rather than given an invented endpoint.

****Connected work** 3 headless operations**

**Integration:** `product-solution-renderer` · **Native key:** `module.connected-work`
**API roots:** `/api/modules/record-graph`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/record-graph/records` | `searchRecordGraph` | `parseRecordGraphSearch` |
| **GET**
`/api/modules/record-graph/{recordId:guid}` | `getRecordGraph` | `parseRecordGraph` |
| **GET**
`/api/runtime/record-scope/records/{recordId:guid}/pages` | `getNativeRecordPages` | `parseNativeRecordPages` |

****Knowledge finder** 3 headless operations**

**Integration:** `product-solution-renderer` · **Native key:** `module.knowledge-finder`
**API roots:** `/api/modules/knowledge-core`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/knowledge-core` | `listKnowledgeCore` | `parseKnowledgeCoreList` |
| **GET**
`/api/modules/knowledge-core/{recordId:guid}` | `getKnowledgeCore` | `parseKnowledgeCoreDetail` |
| **GET**
`/api/runtime/record-scope/records/{recordId:guid}/pages` | `getNativeRecordPages` | `parseNativeRecordPages` |

****Universal Inbox** 22 headless operations**

**Integration:** `shell-and-page-component` · **Native key:** `core.universal-inbox`
**API roots:** `/api/inbox`, `/api/inbox/items`
**Typed client methods:** `list`, `get`, `badge`, `badgeIndicator`, `notifications`, `deliveryDebug`, `retryDelivery`, `setReadState`, `setStatus`, `setPriority`, `setAssignment`, `reply`, `getChannelTicketingSettings`, `setChannelTicketing`, `getEmailTicketingSettings`, `setEmailTicketing`, `decideWorkflowApproval`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/inbox/support-lanes` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/inbox/support-lanes/{laneId:guid}` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/inbox/support-lanes/options` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/inbox/support-lanes` | `Use the typed transport/client` | `Use the returned typed contract` |
| **PUT**
`/api/inbox/support-lanes/{laneId:guid}` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/inbox/support-lanes/{laneId:guid}/retire` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/inbox/lego-catalog` | `getInboxLegoCatalog` | `parseSuccessfulResponse` |
| **GET**
`/api/inbox/lego-presentation` | `getInboxLegoPresentation` | `parseSuccessfulResponse` |
| **GET**
`/api/inbox/items` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/inbox/email-channels/ticketing` | `Use the typed transport/client` | `Use the returned typed contract` |
| **PUT**
`/api/inbox/email-channels/{channelConnectionId:guid}/ticketing` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/inbox/items/{inboxItemId:guid}` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/inbox/badge` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/inbox/notifications` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/inbox/delivery/debug` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/inbox/delivery/{outboundMessageId:guid}/retry` | `Use the typed transport/client` | `Use the returned typed contract` |
| **PUT**
`/api/inbox/items/{inboxItemId:guid}/human-state` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/inbox/badge/indicator` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/inbox/channels/ticketing` | `Use the typed transport/client` | `Use the returned typed contract` |
| **PUT**
`/api/inbox/channels/{channelConnectionId:guid}/ticketing` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/inbox/items/{inboxItemId:guid}/reply` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/inbox/items/{inboxItemId:guid}/workflow-approval` | `Use the typed transport/client` | `Use the returned typed contract` |

****Checklists & Signoffs** 17 headless operations**

**Integration:** `page-module` · **Native key:** `module.checklists-signoffs`
**API roots:** `/api/modules/checklists-signoffs`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/checklists-signoffs/lego/catalog` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/checklists-signoffs/lookups/{lookupId:guid}` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/checklists-signoffs/templates` | `listChecklistTemplates` | `parseChecklistTemplateList` |
| **POST**
`/api/modules/checklists-signoffs/templates` | `createChecklistTemplate` | `parseChecklistMutation` |
| **GET**
`/api/modules/checklists-signoffs/templates/{checklistTemplateId:guid}` | `getChecklistTemplate` | `parseChecklistTemplateDetail` |
| **PUT**
`/api/modules/checklists-signoffs/templates/{checklistTemplateId:guid}` | `updateChecklistTemplate` | `parseChecklistMutation` |
| **DELETE**
`/api/modules/checklists-signoffs/templates/{checklistTemplateId:guid}` | `removeChecklistTemplate` | `parseChecklistTemplateRemoval` |
| **GET**
`/api/modules/checklists-signoffs/runs` | `listChecklistRuns` | `parseChecklistRunList` |
| **GET**
`/api/modules/checklists-signoffs/runs/{checklistRunId:guid}` | `getChecklistRun` | `parseChecklistRunDetail` |
| **POST**
`/api/modules/checklists-signoffs/runs` | `startChecklistRun` | `parseChecklistMutation` |
| **PUT**
`/api/modules/checklists-signoffs/items/{checklistRunItemId:guid}` | `updateChecklistItem` | `parseChecklistMutation` |
| **POST**
`/api/modules/checklists-signoffs/items/{checklistRunItemId:guid}/proof` | `attachChecklistProof` | `parseChecklistMutation` |
| **DELETE**
`/api/modules/checklists-signoffs/proof/{checklistItemEvidenceId:guid}` | `removeChecklistProof` | `parseChecklistMutation` |
| **POST**
`/api/modules/checklists-signoffs/runs/{checklistRunId:guid}/submit` | `submitChecklistForSignoff` | `parseChecklistMutation` |
| **POST**
`/api/modules/checklists-signoffs/runs/{checklistRunId:guid}/cancel` | `cancelChecklistRun` | `parseChecklistCancellation` |
| **GET**
`/api/modules/checklists-signoffs/export/capability` | `getChecklistExportCapability` | `parseModuleExportCapability` |
| **GET**
`/api/modules/checklists-signoffs/export` | `Use the typed transport/client` | `Use the returned typed contract` |

****GoClaw** 8 headless operations**

**Integration:** `shell-and-page-component` · **Native key:** `module.goclaw`
**API roots:** `/api/goclaw/agents`, `/api/goclaw/approvals`
**Typed client methods:** `list`, `approve`, `reject`, `takeOver`, `retry`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/goclaw/approvals` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/goclaw/approvals/lego/catalog` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/goclaw/approvals/lego/presentation` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/goclaw/approvals/{suggestionBatchId:guid}/approve` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/goclaw/approvals/{suggestionBatchId:guid}/reject` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/goclaw/approvals/{suggestionBatchId:guid}/take-over` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/goclaw/approvals/{suggestionBatchId:guid}/retry` | `Use the typed transport/client` | `Use the returned typed contract` |
| **PUT**
`/api/goclaw/agents/{goClawAgentId:guid}/authority` | `Use the typed transport/client` | `Use the returned typed contract` |

****AI Insights** 8 headless operations**

**Integration:** `page-module` · **Native key:** `module.ai-insights`
**API roots:** `/api/modules/ai-insights`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/ai-insights` | `listAiInsights` | `parseAiInsightList` |
| **GET**
`/api/modules/ai-insights/{insightId:guid}` | `getAiInsight` | `parseAiInsightDetail` |
| **PUT**
`/api/modules/ai-insights/{insightId:guid}/state` | `setAiInsightState` | `parseAiInsightState` |
| **GET**
`/api/modules/ai-insights/settings` | `Use the typed transport/client` | `Use the returned typed contract` |
| **PUT**
`/api/modules/ai-insights/settings` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/modules/ai-insights/settings/directives` | `Use the typed transport/client` | `Use the returned typed contract` |
| **PUT**
`/api/modules/ai-insights/settings/directives/{directiveId:guid}` | `Use the typed transport/client` | `Use the returned typed contract` |
| **PUT**
`/api/modules/ai-insights/settings/starters/{directiveId:guid}` | `Use the typed transport/client` | `Use the returned typed contract` |

****Contacts** 16 headless operations**

**Integration:** `page-module` · **Native key:** `module.contacts`
**API roots:** `/api/modules/contacts`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/contacts/schema` | `getContactsLegoCatalog` | `parseSuccessfulResponse` |
| **GET**
`/api/modules/contacts/lookups/{lookupId:guid}` | `getContactsLegoLookup` | `parseSuccessfulResponse` |
| **GET**
`/api/modules/contacts/create-visibility-options` | `getContactCreateVisibilityOptions` | `Use the returned typed contract` |
| **GET**
`/api/modules/contacts` | `listContacts` | `parseContactList, parseSecuredRecordCount` |
| **GET**
`/api/modules/contacts/count` | `listContacts` | `parseContactList, parseSecuredRecordCount` |
| **GET**
`/api/modules/contacts/list-preferences` | `Use the typed transport/client` | `Use the returned typed contract` |
| **PUT**
`/api/modules/contacts/list-preferences/{scope}` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/contacts/{recordId:guid}` | `getContact` | `parseContactDetail` |
| **POST**
`/api/modules/contacts` | `createContact` | `parseContactMutation` |
| **PUT**
`/api/modules/contacts/{recordId:guid}` | `updateContact` | `parseContactMutation` |
| **DELETE**
`/api/modules/contacts/{recordId:guid}` | `removeContact` | `parseContactRemoval` |
| **PUT**
`/api/modules/contacts/{recordId:guid}/favorite` | `setContactFavorite` | `parseContactMutation` |
| **POST**
`/api/modules/contacts/{recordId:guid}/secure-fields/{fieldDefinitionId:guid}/reveal` | `revealContactSecureField` | `parseContactSecureFieldReveal` |
| **PUT**
`/api/modules/contacts/{recordId:guid}/secure-fields/{fieldDefinitionId:guid}` | `setContactSecureField` | `parseContactSecureFieldMutation` |
| **GET**
`/api/modules/contacts/export/capability` | `getContactExportCapability` | `parseContactExportCapability` |
| **GET**
`/api/modules/contacts/export` | `exportContacts` | `Use the returned typed contract` |

****Work Orders** 12 headless operations**

**Integration:** `page-module` · **Native key:** `module.work-orders`
**API roots:** `/api/modules/work-orders`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/work-orders/schema` | `getWorkOrderLegoCatalog` | `parseSuccessfulResponse` |
| **GET**
`/api/modules/work-orders/lookups/{lookupId:guid}` | `getWorkOrderLegoLookup` | `parseSuccessfulResponse` |
| **GET**
`/api/modules/work-orders/{recordId:guid}/status-transitions` | `getWorkOrderStatusTransitions` | `parseSuccessfulResponse` |
| **GET**
`/api/modules/work-orders` | `listWorkOrders` | `parseWorkOrderList` |
| **GET**
`/api/modules/work-orders/{recordId:guid}` | `getWorkOrder` | `parseWorkOrderDetail` |
| **POST**
`/api/modules/work-orders` | `createWorkOrder` | `parseWorkOrderMutation` |
| **PUT**
`/api/modules/work-orders/{recordId:guid}` | `updateWorkOrder` | `parseWorkOrderMutation` |
| **DELETE**
`/api/modules/work-orders/{recordId:guid}` | `removeWorkOrder` | `parseWorkOrderRemoval` |
| **PUT**
`/api/modules/work-orders/{recordId:guid}/status` | `setWorkOrderStatus` | `parseWorkOrderMutation` |
| **PUT**
`/api/modules/work-orders/{recordId:guid}/assignment` | `assignWorkOrder` | `parseWorkOrderMutation` |
| **GET**
`/api/modules/work-orders/export/capability` | `getWorkOrderExportCapability` | `parseModuleExportCapability` |
| **GET**
`/api/modules/work-orders/export` | `Use the typed transport/client` | `Use the returned typed contract` |

****Reservations** 14 headless operations**

**Integration:** `page-module` · **Native key:** `module.reservations`
**API roots:** `/api/modules/reservations`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/reservations/products` | `listReservationProducts` | `parseReservationProductList` |
| **POST**
`/api/modules/reservations/products` | `saveReservationProduct` | `parseReservationMutation` |
| **GET**
`/api/modules/reservations` | `listReservations` | `parseReservationList` |
| **GET**
`/api/modules/reservations/assignees` | `listReservationAssignees` | `parseReservationAssigneeLookup` |
| **GET**
`/api/modules/reservations/capabilities` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/reservations/{recordId:guid}` | `getReservation` | `parseReservationDetail` |
| **POST**
`/api/modules/reservations/purchase` | `purchaseReservation` | `parseReservationMutation` |
| **PUT**
`/api/modules/reservations/{recordId:guid}/status` | `setReservationStatus` | `parseReservationMutation` |
| **PUT**
`/api/modules/reservations/{recordId:guid}/schedule` | `rescheduleReservation` | `parseReservationMutation` |
| **PUT**
`/api/modules/reservations/{recordId:guid}/custom-fields` | `updateReservationCustomFields` | `parseReservationMutation` |
| **PUT**
`/api/modules/reservations/{recordId:guid}/followups` | `updateReservationFollowup` | `parseReservationMutation` |
| **GET**
`/api/modules/reservations/lego/catalog` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/reservations/export/capability` | `getReservationExportCapability` | `parseModuleExportCapability` |
| **GET**
`/api/modules/reservations/export` | `exportReservations` | `Use the returned typed contract` |

****Calendar** 8 headless operations**

**Integration:** `page-module` · **Native key:** `module.calendar`
**API roots:** `/api/modules/calendar`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/calendar` | `listCalendarEvents` | `parseCalendarEventList` |
| **GET**
`/api/modules/calendar/{recordId:guid}` | `getCalendarEvent` | `parseCalendarEventDetail` |
| **POST**
`/api/modules/calendar` | `createCalendarEvent` | `parseCalendarMutation` |
| **PUT**
`/api/modules/calendar/{recordId:guid}` | `updateCalendarEvent` | `parseCalendarMutation` |
| **GET**
`/api/modules/calendar/capabilities` | `Use the typed transport/client` | `Use the returned typed contract` |
| **DELETE**
`/api/modules/calendar/{recordId:guid}` | `removeCalendarEvent` | `parseCalendarRemoval` |
| **PUT**
`/api/modules/calendar/{recordId:guid}/favorite` | `setCalendarFavorite` | `parseCalendarMutation` |
| **GET**
`/api/modules/calendar/lego/catalog` | `Use the typed transport/client` | `Use the returned typed contract` |

****Files** 20 headless operations**

**Integration:** `page-module` · **Native key:** `module.files`
**API roots:** `/api/modules/files`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/files` | `listFiles` | `parseFileList` |
| **GET**
`/api/modules/files/capabilities` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/files/personal-limit` | `Use the typed transport/client` | `Use the returned typed contract` |
| **PUT**
`/api/modules/files/personal-limit` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/files/{recordId:guid}` | `getFile` | `parseFileDetail` |
| **POST**
`/api/modules/files/upload` | `uploadFile` | `parseFileMutation` |
| **PUT**
`/api/modules/files/{recordId:guid}` | `updateFile` | `parseFileMutation` |
| **DELETE**
`/api/modules/files/{recordId:guid}` | `removeFile` | `parseFileRemoval` |
| **POST**
`/api/modules/files/{recordId:guid}/attachments` | `attachFile` | `parseFileMutation` |
| **DELETE**
`/api/modules/files/{recordId:guid}/attachments/{attachmentId:guid}` | `detachFile` | `parseFileMutation` |
| **PUT**
`/api/modules/files/{recordId:guid}/favorite` | `setFileFavorite` | `parseFileMutation` |
| **GET**
`/api/modules/files/{recordId:guid}/comments` | `listFileComments` | `parseFileCommentPage` |
| **POST**
`/api/modules/files/{recordId:guid}/comments` | `addFileComment` | `parseFileCommentReceipt` |
| **DELETE**
`/api/modules/files/{recordId:guid}/comments/{commentId:guid}` | `removeFileComment` | `parseFileCommentRemoval` |
| **GET**
`/api/modules/files/lego/catalog` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/files/{recordId:guid}/content` | `downloadFileContent` | `Use the returned typed contract` |
| **POST**
`/api/modules/files/{recordId:guid}/versions` | `uploadFileVersion` | `parseFileMutation` |
| **GET**
`/api/modules/files/{recordId:guid}/versions` | `listFileVersions` | `parseFileVersionPage` |
| **GET**
`/api/modules/files/{recordId:guid}/versions/{version:int}/content` | `downloadFileVersionContent` | `Use the returned typed contract` |
| **GET**
`/api/tenant/native-message-attachments/{recordId:guid}/content` | `downloadNativeMessageAttachment` | `Use the returned typed contract` |

****Conversations** 13 headless operations**

**Integration:** `page-module` · **Native key:** `module.conversations`
**API roots:** `/api/modules/conversations`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/conversations` | `listConversations` | `parseConversationList` |
| **GET**
`/api/modules/conversations/{recordId:guid}` | `getConversation` | `parseConversationDetail` |
| **GET**
`/api/modules/conversations/{recordId:guid}/messages/{messageId:guid}/attachments/{fileId:guid}/content` | `downloadConversationAttachment` | `Use the returned typed contract` |
| **POST**
`/api/modules/conversations` | `createConversation` | `parseConversationMutation` |
| **PUT**
`/api/modules/conversations/{recordId:guid}` | `updateConversation` | `parseConversationMutation` |
| **GET**
`/api/modules/conversations/lego-catalog` | `getConversationsLegoCatalog` | `parseSuccessfulResponse` |
| **GET**
`/api/modules/conversations/lego-presentation` | `getConversationsLegoPresentation` | `parseSuccessfulResponse` |
| **GET**
`/api/modules/conversations/capabilities` | `Use the typed transport/client` | `Use the returned typed contract` |
| **DELETE**
`/api/modules/conversations/{recordId:guid}` | `removeConversation` | `parseConversationRemoval` |
| **POST**
`/api/modules/conversations/{recordId:guid}/messages` | `postConversationMessage` | `parseConversationMutation` |
| **GET**
`/api/modules/conversations/direct/scope` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/modules/conversations/direct` | `sendDirectConversation` | `parseConversationMutation` |
| **PUT**
`/api/modules/conversations/{recordId:guid}/favorite` | `setConversationFavorite` | `parseConversationMutation` |

****Company news** 9 headless operations**

**Integration:** `page-module` · **Native key:** `module.company-news`
**API roots:** `/api/modules/company-news`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/company-news/schema` | `getCompanyNewsLegoCatalog` | `parseSuccessfulResponse` |
| **GET**
`/api/modules/company-news/lookups/{lookupId:guid}` | `getCompanyNewsLegoLookup` | `parseSuccessfulResponse` |
| **GET**
`/api/modules/company-news` | `listCompanyNews` | `parseCompanyNewsList` |
| **GET**
`/api/modules/company-news/{recordId:guid}` | `getCompanyNews` | `parseCompanyNewsDetail` |
| **POST**
`/api/modules/company-news` | `createCompanyNews` | `parseCompanyNewsMutation` |
| **PUT**
`/api/modules/company-news/{recordId:guid}` | `updateCompanyNews` | `parseCompanyNewsMutation` |
| **PUT**
`/api/modules/company-news/{recordId:guid}/favorite` | `setCompanyNewsFavorite` | `parseCompanyNewsMutation` |
| **PUT**
`/api/modules/company-news/{recordId:guid}/published` | `setCompanyNewsPublished` | `parseCompanyNewsMutation` |
| **DELETE**
`/api/modules/company-news/{recordId:guid}` | `removeCompanyNews` | `parseCompanyNewsRemoval` |

****Knowledge Core** 43 headless operations**

**Integration:** `page-module` · **Native key:** `module.knowledge-articles`
**API roots:** `/api/modules/knowledge-articles`, `/api/modules/knowledge-core`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/knowledge-articles` | `listKnowledgeArticles` | `parseKnowledgeArticlesList` |
| **GET**
`/api/modules/knowledge-articles/{recordId:guid}` | `getKnowledgeArticle` | `parseKnowledgeArticleDetail` |
| **POST**
`/api/modules/knowledge-articles` | `createKnowledgeArticle` | `parseKnowledgeArticleMutation` |
| **PUT**
`/api/modules/knowledge-articles/{recordId:guid}` | `updateKnowledgeArticle` | `parseKnowledgeArticleMutation` |
| **PUT**
`/api/modules/knowledge-articles/{recordId:guid}/favorite` | `setKnowledgeArticleFavorite` | `parseKnowledgeArticleMutation` |
| **DELETE**
`/api/modules/knowledge-articles/{recordId:guid}` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/knowledge-articles/lego/catalog` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/knowledge-core` | `listKnowledgeCore` | `parseKnowledgeCoreList` |
| **GET**
`/api/modules/knowledge-core/{recordId:guid}` | `getKnowledgeCore` | `parseKnowledgeCoreDetail` |
| **POST**
`/api/modules/knowledge-core` | `createKnowledgeCore` | `parseKnowledgeCoreMutation` |
| **PUT**
`/api/modules/knowledge-core/{recordId:guid}` | `updateKnowledgeCore` | `parseKnowledgeCoreMutation` |
| **POST**
`/api/modules/knowledge-core/{recordId:guid}/publish` | `publishKnowledgeCore` | `parseKnowledgeCoreMutation` |
| **POST**
`/api/modules/knowledge-core/{recordId:guid}/archive` | `archiveKnowledgeCore` | `parseKnowledgeCoreMutation` |
| **GET**
`/api/modules/knowledge-core/{recordId:guid}/revisions` | `getKnowledgeCoreRevisions` | `parseKnowledgeRevisions` |
| **POST**
`/api/modules/knowledge-core/{recordId:guid}/restore` | `restoreKnowledgeCoreRevision` | `parseKnowledgeCoreMutation` |
| **GET**
`/api/modules/knowledge-core/collections` | `listKnowledgeCoreCollections` | `parseKnowledgeCollections` |
| **POST**
`/api/modules/knowledge-core/collections` | `createKnowledgeCoreCollection` | `parseKnowledgeCollectionMutation` |
| **PUT**
`/api/modules/knowledge-core/collections/{collectionId:guid}` | `updateKnowledgeCoreCollection` | `parseKnowledgeCollectionMutation` |
| **POST**
`/api/modules/knowledge-core/collections/{collectionId:guid}/items/{recordId:guid}` | `addKnowledgeCoreCollectionItem` | `parseKnowledgeCollectionMutation` |
| **DELETE**
`/api/modules/knowledge-core/collections/{collectionId:guid}/items/{recordId:guid}` | `removeKnowledgeCoreCollectionItem` | `parseKnowledgeCollectionMutation` |
| **GET**
`/api/modules/knowledge-core/{recordId:guid}/owners` | `getKnowledgeCoreOwners` | `parseKnowledgeOwners` |
| **POST**
`/api/modules/knowledge-core/{recordId:guid}/owners` | `setKnowledgeCoreOwner` | `parseKnowledgeOwnerMutation` |
| **DELETE**
`/api/modules/knowledge-core/owners/{knowledgeOwnerId:guid}` | `removeKnowledgeCoreOwner` | `parseKnowledgeOwnerMutation` |
| **GET**
`/api/modules/knowledge-core/unowned` | `listUnownedKnowledgeCore` | `parseKnowledgeCoreList` |
| **GET**
`/api/modules/knowledge-core/assignment-lookup` | `getKnowledgeAssignmentLookup` | `parseKnowledgeAssignmentLookup` |
| **GET**
`/api/modules/knowledge-core/reviews` | `listKnowledgeReviews` | `parseKnowledgeReviews` |
| **POST**
`/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/begin` | `beginKnowledgeReview` | `parseKnowledgeReviewMutation` |
| **POST**
`/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/complete` | `completeKnowledgeReview` | `parseKnowledgeReviewMutation` |
| **POST**
`/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/reassign` | `reassignKnowledgeReview` | `parseKnowledgeReviewMutation` |
| **GET**
`/api/modules/knowledge-core/health` | `getKnowledgeHealth` | `parseKnowledgeHealth` |
| **GET**
`/api/modules/knowledge-core/questions` | `listKnowledgeQuestions` | `parseKnowledgeQuestions` |
| **POST**
`/api/modules/knowledge-core/questions` | `createKnowledgeQuestion` | `parseKnowledgeQuestionMutation` |
| **PUT**
`/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/close` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/assign` | `assignKnowledgeQuestion` | `parseKnowledgeQuestionMutation` |
| **POST**
`/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/answer` | `answerKnowledgeQuestion` | `parseKnowledgeQuestionMutation` |
| **POST**
`/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/convert` | `convertKnowledgeQuestion` | `parseKnowledgeQuestionMutation` |
| **POST**
`/api/modules/knowledge-core/{recordId:guid}/feedback` | `recordKnowledgeFeedback` | `parseKnowledgeFeedbackMutation` |
| **GET**
`/api/modules/knowledge-core/{recordId:guid}/feedback` | `getKnowledgeFeedback` | `parseKnowledgeFeedbackSummary` |
| **GET**
`/api/modules/knowledge-core/{recordId:guid}/feedback/comments` | `listKnowledgeFeedbackComments` | `parseKnowledgeFeedbackCommentPage` |
| **GET**
`/api/modules/knowledge-core/gaps` | `getKnowledgeGaps` | `parseKnowledgeGaps` |
| **GET**
`/api/modules/knowledge-core/support-learning/candidates` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/modules/knowledge-core/support-learning/candidates` | `Use the typed transport/client` | `Use the returned typed contract` |

****Web links** 8 headless operations**

**Integration:** `page-module` · **Native key:** `module.web-links`
**API roots:** `/api/modules/web-links`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/web-links/lego/catalog` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/web-links/lookups/{lookupId:guid}` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/web-links` | `listWebLinks` | `parseWebLinksList` |
| **GET**
`/api/modules/web-links/{recordId:guid}` | `getWebLink` | `parseWebLinkDetail` |
| **POST**
`/api/modules/web-links` | `createWebLink` | `parseWebLinkMutation` |
| **PUT**
`/api/modules/web-links/{recordId:guid}` | `updateWebLink` | `parseWebLinkMutation` |
| **DELETE**
`/api/modules/web-links/{recordId:guid}` | `removeWebLink` | `parseWebLinkRemoval` |
| **PUT**
`/api/modules/web-links/{recordId:guid}/favorite` | `setWebLinkFavorite` | `parseWebLinkMutation` |

****Chat rooms** 14 headless operations**

**Integration:** `page-module` · **Native key:** `module.chat-rooms`
**API roots:** `/api/modules/chat-rooms`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/chat-rooms` | `listChatRooms` | `parseChatRoomsList` |
| **GET**
`/api/modules/chat-rooms/{recordId:guid}` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/modules/chat-rooms` | `createChatRoom` | `parseChatRoomMutation` |
| **PUT**
`/api/modules/chat-rooms/{recordId:guid}` | `updateChatRoom` | `parseChatRoomMutation` |
| **GET**
`/api/modules/chat-rooms/lego/catalog` | `Use the typed transport/client` | `Use the returned typed contract` |
| **DELETE**
`/api/modules/chat-rooms/{recordId:guid}` | `removeChatRoom` | `parseChatRoomRemoval` |
| **POST**
`/api/modules/chat-rooms/{recordId:guid}/messages` | `postChatMessage` | `parseChatRoomMutation` |
| **PUT**
`/api/modules/chat-rooms/{recordId:guid}/messages/{chatMessageId:guid}` | `updateChatMessage` | `parseChatRoomMutation` |
| **DELETE**
`/api/modules/chat-rooms/{recordId:guid}/messages/{chatMessageId:guid}` | `removeChatMessage` | `parseChatRoomMutation` |
| **PUT**
`/api/modules/chat-rooms/{recordId:guid}/messages/{chatMessageId:guid}/reaction` | `setChatReaction` | `parseChatRoomMutation` |
| **PUT**
`/api/modules/chat-rooms/{recordId:guid}/members/{memberUserId:guid}` | `setChatRoomMember` | `parseChatRoomMutation` |
| **GET**
`/api/modules/chat-rooms/{recordId:guid}/members/lookup` | `getChatRoomMemberLookup` | `parseChatRoomMemberLookup` |
| **PUT**
`/api/modules/chat-rooms/{recordId:guid}/read` | `markChatRoomRead` | `parseChatRoomMutation` |
| **PUT**
`/api/modules/chat-rooms/{recordId:guid}/favorite` | `setChatRoomFavorite` | `parseChatRoomMutation` |

****Discussion Boards** 14 headless operations**

**Integration:** `page-module` · **Native key:** `module.discussion-boards`
**API roots:** `/api/modules/discussion-boards`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/discussion-boards` | `listDiscussionBoards` | `parseDiscussionBoardsList` |
| **GET**
`/api/modules/discussion-boards/{recordId:guid}` | `getDiscussionBoard` | `parseDiscussionBoardDetail` |
| **POST**
`/api/modules/discussion-boards` | `createDiscussionBoard` | `parseDiscussionMutation` |
| **PUT**
`/api/modules/discussion-boards/{recordId:guid}` | `updateDiscussionBoard` | `parseDiscussionMutation` |
| **GET**
`/api/modules/discussion-boards/lego/catalog` | `Use the typed transport/client` | `Use the returned typed contract` |
| **DELETE**
`/api/modules/discussion-boards/{recordId:guid}` | `removeDiscussionBoard` | `parseDiscussionBoardRemoval` |
| **POST**
`/api/modules/discussion-boards/{boardRecordId:guid}/topics` | `createDiscussionTopic` | `parseDiscussionMutation` |
| **GET**
`/api/modules/discussion-boards/topics/{recordId:guid}` | `Use the typed transport/client` | `Use the returned typed contract` |
| **PUT**
`/api/modules/discussion-boards/topics/{recordId:guid}` | `updateDiscussionTopic` | `parseDiscussionMutation` |
| **DELETE**
`/api/modules/discussion-boards/topics/{recordId:guid}` | `removeDiscussionTopic` | `parseDiscussionTopicRemoval` |
| **POST**
`/api/modules/discussion-boards/topics/{topicRecordId:guid}/posts` | `postDiscussionReply` | `parseDiscussionMutation` |
| **PUT**
`/api/modules/discussion-boards/posts/{recordId:guid}` | `updateDiscussionPost` | `parseDiscussionMutation` |
| **DELETE**
`/api/modules/discussion-boards/posts/{recordId:guid}` | `removeDiscussionPost` | `parseDiscussionPostRemoval` |
| **PUT**
`/api/modules/discussion-boards/records/{recordId:guid}/favorite` | `setDiscussionFavorite` | `parseDiscussionMutation` |

****Mail reader** 10 headless operations**

**Integration:** `page-module` · **Native key:** `module.mail-reader`
**API roots:** `/api/modules/mail-reader`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/mail-reader` | `listMailReaderMessages` | `parseMailReaderList` |
| **GET**
`/api/modules/mail-reader/{recordId:guid}` | `getMailReaderMessage` | `parseMailReaderDetail` |
| **PUT**
`/api/modules/mail-reader/{recordId:guid}/read` | `setMailReaderRead` | `Use the returned typed contract` |
| **POST**
`/api/modules/mail-reader/{recordId:guid}/archive` | `archiveMailReaderMessage` | `Use the returned typed contract` |
| **GET**
`/api/modules/mail-reader/mailboxes` | `listMailReaderMailboxes` | `parseMailReaderMailboxes` |
| **POST**
`/api/modules/mail-reader/mailboxes` | `createMailReaderMailbox` | `parseMailReaderMailboxMutation` |
| **PUT**
`/api/modules/mail-reader/mailboxes/{mailboxId:guid}` | `updateMailReaderMailbox` | `parseMailReaderMailboxMutation` |
| **PUT**
`/api/modules/mail-reader/{recordId:guid}/favorite` | `setMailReaderFavorite` | `Use the returned typed contract` |
| **PUT**
`/api/modules/mail-reader/mailboxes/{mailboxRecordId:guid}/credentials/{purpose}` | `setMailReaderCredential` | `parseMailReaderCredentialStatus` |
| **POST**
`/api/modules/mail-reader/mailboxes/{mailboxRecordId:guid}/compose` | `composeMailReaderEmail` | `parseMailReaderComposeResult` |

****Favorites** 7 headless operations**

**Integration:** `page-module` · **Native key:** `module.favorites`
**API roots:** `/api/modules/favorites`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/favorites/schema` | `getFavoritesLegoCatalog` | `parseSuccessfulResponse` |
| **GET**
`/api/modules/favorites/presentation` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/favorites` | `listFavorites` | `parseFavoritesList` |
| **GET**
`/api/modules/favorites/{recordId:guid}` | `getFavorite` | `parseFavoriteDetail` |
| **GET**
`/api/modules/favorites/{recordId:guid}/state` | `getFavoriteState` | `parseFavoriteMutation` |
| **PUT**
`/api/modules/favorites/{recordId:guid}/favorite` | `setFavorite` | `parseFavoriteMutation` |
| **PUT**
`/api/modules/favorites/{recordId:guid}/preferences` | `updateFavoritePreferences` | `parseFavoriteMutation` |

****Notifications** 6 headless operations**

**Integration:** `page-module` · **Native key:** `module.notifications`
**API roots:** `/api/modules/notifications`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/notifications` | `listNotifications` | `parseNotificationList` |
| **GET**
`/api/modules/notifications/lego-catalog` | `getNotificationsLegoCatalog` | `parseSuccessfulResponse` |
| **GET**
`/api/modules/notifications/lego-presentation` | `getNotificationsLegoPresentation` | `parseSuccessfulResponse` |
| **GET**
`/api/modules/notifications/{notificationId:guid}` | `getNotification` | `parseNotificationDetail` |
| **PUT**
`/api/modules/notifications/{notificationId:guid}/state` | `setNotificationState` | `parseNotificationMutation` |
| **PUT**
`/api/modules/notifications/{notificationId:guid}/source-favorite` | `setNotificationSourceFavorite` | `parseNotificationMutation` |

****Dynamic Records** 13 headless operations**

**Integration:** `page-module` · **Native key:** `module.dynamic-records`
**API roots:** `/api/modules/dynamic`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/dynamic` | `listDynamicModuleSchemas` | `parseDynamicModuleCatalog` |
| **GET**
`/api/modules/dynamic/{moduleKey}/schema` | `getDynamicModuleSchema` | `parseDynamicModuleSchema` |
| **GET**
`/api/modules/dynamic/{moduleKey}/lookups/{lookupId:guid}` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/dynamic/{moduleKey}/lego/catalog` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/dynamic/{moduleKey}` | `listDynamicModuleRecords` | `parseDynamicModuleList` |
| **GET**
`/api/modules/dynamic/{moduleKey}/{recordId:guid}` | `getDynamicModuleRecord` | `parseDynamicModuleDetail` |
| **POST**
`/api/modules/dynamic/{moduleKey}` | `createDynamicModuleRecord` | `parseDynamicModuleMutation` |
| **PUT**
`/api/modules/dynamic/{moduleKey}/{recordId:guid}` | `updateDynamicModuleRecord` | `parseDynamicModuleMutation` |
| **DELETE**
`/api/modules/dynamic/{moduleKey}/{recordId:guid}` | `deleteDynamicModuleRecord` | `parseDynamicModuleRemoval` |
| **PUT**
`/api/modules/dynamic/{moduleKey}/{recordId:guid}/favorite` | `setDynamicModuleFavorite` | `parseDynamicModuleMutation` |
| **POST**
`/api/modules/dynamic/caseflow-cases/{recordId:guid}/transition` | `transitionCaseFlowCase` | `Use the returned typed contract` |
| **GET**
`/api/modules/dynamic/{moduleKey}/export/capability` | `getDynamicRecordExportCapability` | `parseModuleExportCapability` |
| **GET**
`/api/modules/dynamic/{moduleKey}/export` | `Use the typed transport/client` | `Use the returned typed contract` |

****ActiveWorkplace** 14 headless operations**

**Integration:** `page-module` · **Native key:** `module.active-workplace`
**API roots:** `/api/modules/active-workplace`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/active-workplace` | `listActiveWorkplaces` | `parseActiveWorkplaceList` |
| **GET**
`/api/modules/active-workplace/lego/catalog` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/active-workplace/lego/lookups/{lookupId:guid}` | `Use the typed transport/client` | `Use the returned typed contract` |
| **GET**
`/api/modules/active-workplace/lego/presentation` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/modules/active-workplace` | `createActiveWorkplace` | `parseActiveWorkplaceMutation` |
| **GET**
`/api/modules/active-workplace/{activeWorkplaceId:guid}` | `getActiveWorkplace` | `parseActiveWorkplaceDetail` |
| **PATCH**
`/api/modules/active-workplace/{activeWorkplaceId:guid}` | `updateActiveWorkplace` | `parseActiveWorkplaceMutation` |
| **POST**
`/api/modules/active-workplace/{activeWorkplaceId:guid}/status` | `setActiveWorkplaceStatus` | `parseActiveWorkplaceMutation` |
| **GET**
`/api/modules/active-workplace/{activeWorkplaceId:guid}/participants/catalog` | `getActiveWorkplaceParticipantCatalog` | `parseActiveWorkplaceCatalog` |
| **POST**
`/api/modules/active-workplace/{activeWorkplaceId:guid}/participants` | `addActiveWorkplaceParticipant` | `parseActiveWorkplaceMutation` |
| **DELETE**
`/api/modules/active-workplace/{activeWorkplaceId:guid}/participants/{activeWorkplaceParticipantId:guid}` | `removeActiveWorkplaceParticipant` | `parseActiveWorkplaceMutation` |
| **POST**
`/api/modules/active-workplace/{activeWorkplaceId:guid}/activity` | `recordActiveWorkplaceActivity` | `parseActiveWorkplaceMutation` |
| **POST**
`/api/modules/active-workplace/{activeWorkplaceId:guid}/graph/refresh` | `refreshActiveWorkplaceGraph` | `parseActiveWorkplaceMutation` |
| **GET**
`/api/modules/active-workplace/{activeWorkplaceId:guid}/playback` | `getActiveWorkplacePlayback` | `parseActiveWorkplacePlayback` |

****Record relations** 10 headless operations**

**Integration:** `page-module` · **Native key:** `module.record-graph`
**API roots:** `/api/modules/record-graph`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/record-graph/records` | `searchRecordGraph` | `parseRecordGraphSearch` |
| **GET**
`/api/modules/record-graph/{recordId:guid}` | `getRecordGraph` | `parseRecordGraph` |
| **GET**
`/api/modules/record-graph/{recordId:guid}/relations` | `Use the typed transport/client` | `Use the returned typed contract` |
| **PUT**
`/api/modules/record-graph/{recordId:guid}/relations` | `addRecordGraphRelation` | `parseRecordGraphMutation` |
| **DELETE**
`/api/modules/record-graph/relations/{recordRelationId:guid}` | `removeRecordGraphRelation` | `parseRecordGraphMutation` |
| **PUT**
`/api/modules/record-graph/{recordId:guid}/favorite` | `setRecordGraphFavorite` | `parseFavoriteMutation` |
| **GET**
`/api/modules/record-graph/{recordId:guid}/knowledge` | `getRelatedKnowledge` | `parseRelatedKnowledge` |
| **GET**
`/api/modules/record-graph/{recordId:guid}/knowledge/candidates` | `getContextualKnowledge` | `parseContextualKnowledge` |
| **PUT**
`/api/modules/record-graph/{recordId:guid}/knowledge` | `linkKnowledgeToRecord` | `parseKnowledgeRelationMutation` |
| **DELETE**
`/api/modules/record-graph/knowledge-relations/{recordRelationId:guid}` | `unlinkKnowledgeFromRecord` | `parseKnowledgeRelationMutation` |

****Record activity** 3 headless operations**

**Integration:** `page-module` · **Native key:** `module.record-activity`
**API roots:** `/api/modules/record-activity`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/record-activity/records` | `searchRecordActivity` | `parseRecordActivitySearch` |
| **GET**
`/api/modules/record-activity/{recordId:guid}` | `getRecordActivity` | `parseRecordActivity` |
| **PUT**
`/api/modules/record-activity/{recordId:guid}/favorite` | `setRecordActivityFavorite` | `parseFavoriteMutation` |

****Global secured search** 3 headless operations**

**Integration:** `page-module` · **Native key:** `module.global-search`
**API roots:** `/api/modules/global-search`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/global-search` | `searchGlobalRecords` | `parseGlobalSearch, parseSecuredRecordCount` |
| **GET**
`/api/modules/global-search/count` | `searchGlobalRecords` | `parseGlobalSearch, parseSecuredRecordCount` |
| **PUT**
`/api/modules/global-search/records/{recordId:guid}/favorite` | `setGlobalSearchFavorite` | `parseFavoriteMutation` |

****Account Admin API** 0 headless operations**

**Integration:** `api-surface` · **Native key:** `module.account-admin`
**API roots:** `/api/account-admin`

This API surface supports other first-class modules and has no standalone page renderer.

****Support Lanes API** 0 headless operations**

**Integration:** `api-surface` · **Native key:** `module.support-lanes`
**API roots:** `/api/inbox/support-lanes`

This API surface supports other first-class modules and has no standalone page renderer.

****Company Iq API** 0 headless operations**

**Integration:** `api-surface` · **Native key:** `module.company-iq`
**API roots:** `/api/modules/company-iq`

This API surface supports other first-class modules and has no standalone page renderer.

****Ops Atlas API** 0 headless operations**

**Integration:** `api-surface` · **Native key:** `module.ops-atlas`
**API roots:** `/api/modules/ops-atlas`

This API surface supports other first-class modules and has no standalone page renderer.

****Payments Module API** 14 headless operations**

**Integration:** `api-surface` · **Native key:** `Not a page block`
**API roots:** `/api/modules/payments`

| Exact HTTP route | Current browser function | Response parser |
| --- | --- | --- |
| **GET**
`/api/modules/payments/settings` | `getTenantPaymentSettings` | `parseTenantPaymentSettings` |
| **PUT**
`/api/modules/payments/settings/{moduleKey}` | `updateTenantPaymentPolicy` | `parseTenantPaymentMutation` |
| **PUT**
`/api/modules/payments/connectors` | `upsertTenantPaymentConnector` | `parseTenantPaymentMutation` |
| **DELETE**
`/api/modules/payments/connectors/{connectorId:guid}` | `deactivateTenantPaymentConnector` | `parseTenantPaymentMutation` |
| **GET**
`/api/modules/payments/methods` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/modules/payments/methods` | `registerTenantPaymentMethod` | `parseTenantPaymentMutation` |
| **GET**
`/api/modules/payments/methods/{paymentMethodId:guid}` | `getTenantPaymentMethod` | `parseTenantPaymentMethod` |
| **PUT**
`/api/modules/payments/methods/{paymentMethodId:guid}/default` | `setDefaultTenantPaymentMethod` | `parseTenantPaymentMutation` |
| **DELETE**
`/api/modules/payments/methods/{paymentMethodId:guid}` | `revokeTenantPaymentMethod` | `parseTenantPaymentMutation` |
| **GET**
`/api/modules/payments/records/{recordId:guid}` | `getTenantRecordPayments` | `parseTenantRecordPaymentSummary` |
| **POST**
`/api/modules/payments/records/{recordId:guid}/charges` | `createTenantRecordCharge` | `parseTenantPaymentMutation` |
| **DELETE**
`/api/modules/payments/records/{recordId:guid}/charges/{chargeIntentId:guid}` | `cancelTenantRecordCharge` | `parseTenantPaymentMutation` |
| **GET**
`/api/modules/payments/attention` | `Use the typed transport/client` | `Use the returned typed contract` |
| **POST**
`/api/modules/payments/records/{recordId:guid}/charges/{chargeIntentId:guid}/attention` | `resolveTenantPaymentAttention` | `parseTenantPaymentAttentionReceipt` |

****Record Types API** 0 headless operations**

**Integration:** `api-surface` · **Native key:** `module.record-types`
**API roots:** `/api/runtime/record-types`

This API surface supports other first-class modules and has no standalone page renderer.

**Copy the searchable styled/unstyled operation directory**

```

import { useMemo, useState } from "react";
import { headlessCapabilityRecipes } from "./HeadlessCapabilityRecipes.generated";

export const HeadlessOperationDirectory = ({ styled = false }: { readonly styled?: boolean }) => {
  const [query, setQuery] = useState("");
  const recipes = useMemo(() => {
    const needle = query.trim().toLowerCase();
    return needle ? headlessCapabilityRecipes.filter((recipe) => [recipe.title, recipe.slug, ...recipe.apiBasePaths, ...recipe.operations.flatMap((operation) => [operation.method, operation.route, ...operation.browserFunctions])].some((value) => value.toLowerCase().includes(needle))) : headlessCapabilityRecipes;
  }, [query]);
  return <section className={styled ? "bwhq-headless-directory" : undefined}>
    <header><h1>Headless capability operations</h1><label>Search capability, route, or function<input type="search" value={query} onChange={(event) => setQuery(event.target.value)} /></label></header>
    {recipes.map((recipe) => <details key={recipe.slug}><summary><strong>{recipe.title}</strong> <span>{recipe.operations.length} operations</span></summary><p>{recipe.integrationKind} · {recipe.nativeComponentKey || "No native page block"}</p>{hasOperations(recipe.operations) ? <table><thead><tr><th>HTTP</th><th>Browser function</th><th>Parser</th></tr></thead><tbody>{recipe.operations.map((operation) => <tr key={`${operation.method} ${operation.route}`}><td><strong>{operation.method}</strong><br /><code>{operation.route}</code></td><td>{operation.browserFunctions.join(", ") || "Use typed transport/client"}</td><td>{operation.parsers.join(", ") || "See typed client contract"}</td></tr>)}</tbody></table> : <p>{recipe.integrationNote}</p>}</details>)}
  </section>;
};

const hasOperations = (operations: readonly unknown[]) => operations.length > 0;

export const UnstyledHeadlessOperationDirectory = () => <HeadlessOperationDirectory />;
export const StyledHeadlessOperationDirectory = () => <HeadlessOperationDirectory styled />;
```

**Copy the complete machine-readable headless recipes**

```
export interface HeadlessOperationRecipe {
  readonly method: string;
  readonly route: string;
  readonly browserFunctions: readonly string[];
  readonly parsers: readonly string[];
  readonly procedures: readonly string[];
}

export interface HeadlessCapabilityRecipe {
  readonly slug: string;
  readonly title: string;
  readonly integrationKind: "page-module" | "product-solution-renderer" | "shell-component" | "shell-and-page-component" | "background-service" | "api-surface";
  readonly nativeComponentKey: string | null;
  readonly apiBasePaths: readonly string[];
  readonly clientMethods: readonly string[];
  readonly operations: readonly HeadlessOperationRecipe[];
  readonly integrationNote: string;
}

export const headlessCapabilityRecipes = [
  {
    "slug": "connected-work",
    "title": "Connected work",
    "integrationKind": "product-solution-renderer",
    "nativeComponentKey": "module.connected-work",
    "apiBasePaths": [
      "/api/modules/record-graph"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/record-graph/records",
        "browserFunctions": [
          "searchRecordGraph"
        ],
        "parsers": [
          "parseRecordGraphSearch"
        ],
        "procedures": [
          "sp_RecordGraph_SearchSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/record-graph/{recordId:guid}",
        "browserFunctions": [
          "getRecordGraph"
        ],
        "parsers": [
          "parseRecordGraph"
        ],
        "procedures": [
          "sp_RecordGraph_GetSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/runtime/record-scope/records/{recordId:guid}/pages",
        "browserFunctions": [
          "getNativeRecordPages"
        ],
        "parsers": [
          "parseNativeRecordPages"
        ],
        "procedures": [
          "sp_RecordScope_GetNativePagesSecured"
        ]
      }
    ],
    "integrationNote": "Read-only discovery using the listed existing secured GET contracts. NativeRecordLink resolves persisted native destinations; lifecycle mutations remain on the owning module. Native page resolution is a tenant-runtime contract, not an invented Developer API route."
  },
  {
    "slug": "knowledge-finder",
    "title": "Knowledge finder",
    "integrationKind": "product-solution-renderer",
    "nativeComponentKey": "module.knowledge-finder",
    "apiBasePaths": [
      "/api/modules/knowledge-core"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core",
        "browserFunctions": [
          "listKnowledgeCore"
        ],
        "parsers": [
          "parseKnowledgeCoreList"
        ],
        "procedures": [
          "sp_kc_ListKnowledgeItemsSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core/{recordId:guid}",
        "browserFunctions": [
          "getKnowledgeCore"
        ],
        "parsers": [
          "parseKnowledgeCoreDetail"
        ],
        "procedures": [
          "sp_kc_GetKnowledgeItemSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/runtime/record-scope/records/{recordId:guid}/pages",
        "browserFunctions": [
          "getNativeRecordPages"
        ],
        "parsers": [
          "parseNativeRecordPages"
        ],
        "procedures": [
          "sp_RecordScope_GetNativePagesSecured"
        ]
      }
    ],
    "integrationNote": "Read-only discovery using the listed existing secured GET contracts. NativeRecordLink resolves persisted native destinations; lifecycle mutations remain on the owning module. Native page resolution is a tenant-runtime contract, not an invented Developer API route."
  },
  {
    "slug": "universal-inbox",
    "title": "Universal Inbox",
    "integrationKind": "shell-and-page-component",
    "nativeComponentKey": "core.universal-inbox",
    "apiBasePaths": [
      "/api/inbox",
      "/api/inbox/items"
    ],
    "clientMethods": [
      "list",
      "get",
      "badge",
      "badgeIndicator",
      "notifications",
      "deliveryDebug",
      "retryDelivery",
      "setReadState",
      "setStatus",
      "setPriority",
      "setAssignment",
      "reply",
      "getChannelTicketingSettings",
      "setChannelTicketing",
      "getEmailTicketingSettings",
      "setEmailTicketing",
      "decideWorkflowApproval"
    ],
    "operations": [
      {
        "method": "GET",
        "route": "/api/inbox/support-lanes",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Inbox_ListSupportLanesSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/inbox/support-lanes/{laneId:guid}",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Inbox_ListSupportLanesSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/inbox/support-lanes/options",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Inbox_ListSupportLaneOptionsSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/inbox/support-lanes",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Inbox_SaveSupportLaneSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/inbox/support-lanes/{laneId:guid}",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Inbox_SaveSupportLaneSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/inbox/support-lanes/{laneId:guid}/retire",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Inbox_RetireSupportLaneSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/inbox/lego-catalog",
        "browserFunctions": [
          "getInboxLegoCatalog"
        ],
        "parsers": [
          "parseSuccessfulResponse"
        ],
        "procedures": []
      },
      {
        "method": "GET",
        "route": "/api/inbox/lego-presentation",
        "browserFunctions": [
          "getInboxLegoPresentation"
        ],
        "parsers": [
          "parseSuccessfulResponse"
        ],
        "procedures": [
          "sp_Inbox_GetQueueSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/inbox/items",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Inbox_GetQueueSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/inbox/email-channels/ticketing",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Inbox_GetEmailTicketingSettingsSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/inbox/email-channels/{channelConnectionId:guid}/ticketing",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Inbox_SetEmailTicketingSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/inbox/items/{inboxItemId:guid}",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Inbox_GetItemDetailSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/inbox/badge",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_GetInboxBadgeSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/inbox/notifications",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_GetInboxNotificationsSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/inbox/delivery/debug",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_GetDeliveryDebugSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/inbox/delivery/{outboundMessageId:guid}/retry",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_RetryOutboundMessage"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/inbox/items/{inboxItemId:guid}/human-state",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "WriteAuditLog",
          "sp_Inbox_MarkRead",
          "sp_Inbox_SetStatusSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/inbox/badge/indicator",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_GetInboxBadgeIndicatorSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/inbox/channels/ticketing",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Inbox_GetChannelTicketingSettingsSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/inbox/channels/{channelConnectionId:guid}/ticketing",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Inbox_SetChannelTicketingSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/inbox/items/{inboxItemId:guid}/reply",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Inbox_ReplySecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/inbox/items/{inboxItemId:guid}/workflow-approval",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "checklists-signoffs",
    "title": "Checklists & Signoffs",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.checklists-signoffs",
    "apiBasePaths": [
      "/api/modules/checklists-signoffs"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/checklists-signoffs/lego/catalog",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      },
      {
        "method": "GET",
        "route": "/api/modules/checklists-signoffs/lookups/{lookupId:guid}",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      },
      {
        "method": "GET",
        "route": "/api/modules/checklists-signoffs/templates",
        "browserFunctions": [
          "listChecklistTemplates"
        ],
        "parsers": [
          "parseChecklistTemplateList"
        ],
        "procedures": [
          "sp_Checklists_ListTemplatesSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/checklists-signoffs/templates",
        "browserFunctions": [
          "createChecklistTemplate"
        ],
        "parsers": [
          "parseChecklistMutation"
        ],
        "procedures": [
          "sp_Checklists_CreateTemplateSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/checklists-signoffs/templates/{checklistTemplateId:guid}",
        "browserFunctions": [
          "getChecklistTemplate"
        ],
        "parsers": [
          "parseChecklistTemplateDetail"
        ],
        "procedures": [
          "sp_Checklists_GetTemplateSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/checklists-signoffs/templates/{checklistTemplateId:guid}",
        "browserFunctions": [
          "updateChecklistTemplate"
        ],
        "parsers": [
          "parseChecklistMutation"
        ],
        "procedures": [
          "sp_Checklists_UpdateTemplateSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/checklists-signoffs/templates/{checklistTemplateId:guid}",
        "browserFunctions": [
          "removeChecklistTemplate"
        ],
        "parsers": [
          "parseChecklistTemplateRemoval"
        ],
        "procedures": [
          "sp_Checklists_DeactivateTemplateSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/checklists-signoffs/runs",
        "browserFunctions": [
          "listChecklistRuns"
        ],
        "parsers": [
          "parseChecklistRunList"
        ],
        "procedures": [
          "sp_Checklists_ListRunsSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/checklists-signoffs/runs/{checklistRunId:guid}",
        "browserFunctions": [
          "getChecklistRun"
        ],
        "parsers": [
          "parseChecklistRunDetail"
        ],
        "procedures": [
          "sp_Checklists_GetRunSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/checklists-signoffs/runs",
        "browserFunctions": [
          "startChecklistRun"
        ],
        "parsers": [
          "parseChecklistMutation"
        ],
        "procedures": [
          "sp_Checklists_StartRunSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/checklists-signoffs/items/{checklistRunItemId:guid}",
        "browserFunctions": [
          "updateChecklistItem"
        ],
        "parsers": [
          "parseChecklistMutation"
        ],
        "procedures": [
          "sp_Checklists_UpdateItemSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/checklists-signoffs/items/{checklistRunItemId:guid}/proof",
        "browserFunctions": [
          "attachChecklistProof"
        ],
        "parsers": [
          "parseChecklistMutation"
        ],
        "procedures": [
          "sp_Checklists_AttachProofSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/checklists-signoffs/proof/{checklistItemEvidenceId:guid}",
        "browserFunctions": [
          "removeChecklistProof"
        ],
        "parsers": [
          "parseChecklistMutation"
        ],
        "procedures": [
          "sp_Checklists_RemoveProofSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/checklists-signoffs/runs/{checklistRunId:guid}/submit",
        "browserFunctions": [
          "submitChecklistForSignoff"
        ],
        "parsers": [
          "parseChecklistMutation"
        ],
        "procedures": [
          "sp_Checklists_SubmitForSignoffSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/checklists-signoffs/runs/{checklistRunId:guid}/cancel",
        "browserFunctions": [
          "cancelChecklistRun"
        ],
        "parsers": [
          "parseChecklistCancellation"
        ],
        "procedures": [
          "sp_Checklists_CancelRunSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/checklists-signoffs/export/capability",
        "browserFunctions": [
          "getChecklistExportCapability"
        ],
        "parsers": [
          "parseModuleExportCapability"
        ],
        "procedures": [
          "sp_Checklists_GetExportCapabilitySecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/checklists-signoffs/export",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Checklists_ExportRunsSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "goclaw",
    "title": "GoClaw",
    "integrationKind": "shell-and-page-component",
    "nativeComponentKey": "module.goclaw",
    "apiBasePaths": [
      "/api/goclaw/agents",
      "/api/goclaw/approvals"
    ],
    "clientMethods": [
      "list",
      "approve",
      "reject",
      "takeOver",
      "retry"
    ],
    "operations": [
      {
        "method": "GET",
        "route": "/api/goclaw/approvals",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_AiAction_GetApprovalQueueSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/goclaw/approvals/lego/catalog",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      },
      {
        "method": "GET",
        "route": "/api/goclaw/approvals/lego/presentation",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_AiAction_GetApprovalQueueSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/goclaw/approvals/{suggestionBatchId:guid}/approve",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_AiAction_EditAndApproveSuggestionBatch"
        ]
      },
      {
        "method": "POST",
        "route": "/api/goclaw/approvals/{suggestionBatchId:guid}/reject",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_AiAction_RejectSuggestionBatch"
        ]
      },
      {
        "method": "POST",
        "route": "/api/goclaw/approvals/{suggestionBatchId:guid}/take-over",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_AiAction_ReviewDisposition"
        ]
      },
      {
        "method": "POST",
        "route": "/api/goclaw/approvals/{suggestionBatchId:guid}/retry",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_AiAction_ReviewDisposition"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/goclaw/agents/{goClawAgentId:guid}/authority",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "ai-insights",
    "title": "AI Insights",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.ai-insights",
    "apiBasePaths": [
      "/api/modules/ai-insights"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/ai-insights",
        "browserFunctions": [
          "listAiInsights"
        ],
        "parsers": [
          "parseAiInsightList"
        ],
        "procedures": [
          "sp_AiInsights_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/ai-insights/{insightId:guid}",
        "browserFunctions": [
          "getAiInsight"
        ],
        "parsers": [
          "parseAiInsightDetail"
        ],
        "procedures": [
          "sp_AiInsights_GetSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/ai-insights/{insightId:guid}/state",
        "browserFunctions": [
          "setAiInsightState"
        ],
        "parsers": [
          "parseAiInsightState"
        ],
        "procedures": [
          "sp_AiInsights_SetStateSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/ai-insights/settings",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_AiInsights_GetProducerSettingsSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/ai-insights/settings",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_AiInsights_SaveProducerSettingsSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/ai-insights/settings/directives",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_AiInsights_SaveDirectiveSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/ai-insights/settings/directives/{directiveId:guid}",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_AiInsights_SaveDirectiveSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/ai-insights/settings/starters/{directiveId:guid}",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_AiInsights_SetStarterDirectiveSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "contacts",
    "title": "Contacts",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.contacts",
    "apiBasePaths": [
      "/api/modules/contacts"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/contacts/schema",
        "browserFunctions": [
          "getContactsLegoCatalog"
        ],
        "parsers": [
          "parseSuccessfulResponse"
        ],
        "procedures": [
          "sp_Contacts_GetLegoCatalogSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/contacts/lookups/{lookupId:guid}",
        "browserFunctions": [
          "getContactsLegoLookup"
        ],
        "parsers": [
          "parseSuccessfulResponse"
        ],
        "procedures": [
          "sp_Contacts_GetLegoLookupSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/contacts/create-visibility-options",
        "browserFunctions": [
          "getContactCreateVisibilityOptions"
        ],
        "parsers": [],
        "procedures": [
          "sp_Contacts_GetCreateVisibilityOptionsSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/contacts",
        "browserFunctions": [
          "listContacts"
        ],
        "parsers": [
          "parseContactList",
          "parseSecuredRecordCount"
        ],
        "procedures": [
          "sp_Contacts_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/contacts/count",
        "browserFunctions": [
          "listContacts"
        ],
        "parsers": [
          "parseContactList",
          "parseSecuredRecordCount"
        ],
        "procedures": [
          "sp_Contacts_CountSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/contacts/list-preferences",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_ContactsList_GetPreferencesSecured",
          "sp_ContactsList_GetPublishedDefaults"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/contacts/list-preferences/{scope}",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_ContactsList_SavePreferencesSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/contacts/{recordId:guid}",
        "browserFunctions": [
          "getContact"
        ],
        "parsers": [
          "parseContactDetail"
        ],
        "procedures": [
          "sp_Contacts_GetSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/contacts",
        "browserFunctions": [
          "createContact"
        ],
        "parsers": [
          "parseContactMutation"
        ],
        "procedures": [
          "sp_Contacts_CreateSecured",
          "sp_Contacts_GetSecured",
          "sp_Contacts_UpdateSecured",
          "sp_RecordScope_GetCurrentSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/contacts/{recordId:guid}",
        "browserFunctions": [
          "updateContact"
        ],
        "parsers": [
          "parseContactMutation"
        ],
        "procedures": [
          "sp_Contacts_GetSecured",
          "sp_Contacts_UpdateSecured",
          "sp_RecordScope_GetCurrentSecured",
          "sp_Contacts_CreateSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/contacts/{recordId:guid}",
        "browserFunctions": [
          "removeContact"
        ],
        "parsers": [
          "parseContactRemoval"
        ],
        "procedures": [
          "sp_Contacts_GetSecured",
          "sp_Developer_DeleteRecord",
          "sp_RecordScope_GetCurrentSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/contacts/{recordId:guid}/favorite",
        "browserFunctions": [
          "setContactFavorite"
        ],
        "parsers": [
          "parseContactMutation"
        ],
        "procedures": [
          "sp_Contacts_SetFavoriteSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/contacts/{recordId:guid}/secure-fields/{fieldDefinitionId:guid}/reveal",
        "browserFunctions": [
          "revealContactSecureField"
        ],
        "parsers": [
          "parseContactSecureFieldReveal"
        ],
        "procedures": [
          "sp_Contacts_RevealSecureFieldSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/contacts/{recordId:guid}/secure-fields/{fieldDefinitionId:guid}",
        "browserFunctions": [
          "setContactSecureField"
        ],
        "parsers": [
          "parseContactSecureFieldMutation"
        ],
        "procedures": [
          "sp_Contacts_GetSecured",
          "sp_Contacts_SetSecureFieldSecured",
          "sp_RecordScope_GetCurrentSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/contacts/export/capability",
        "browserFunctions": [
          "getContactExportCapability"
        ],
        "parsers": [
          "parseContactExportCapability"
        ],
        "procedures": [
          "sp_Contacts_GetExportCapabilitySecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/contacts/export",
        "browserFunctions": [
          "exportContacts"
        ],
        "parsers": [],
        "procedures": [
          "sp_Contacts_ExportSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "work-orders",
    "title": "Work Orders",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.work-orders",
    "apiBasePaths": [
      "/api/modules/work-orders"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/work-orders/schema",
        "browserFunctions": [
          "getWorkOrderLegoCatalog"
        ],
        "parsers": [
          "parseSuccessfulResponse"
        ],
        "procedures": [
          "sp_WorkOrders_GetLegoCatalogSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/work-orders/lookups/{lookupId:guid}",
        "browserFunctions": [
          "getWorkOrderLegoLookup"
        ],
        "parsers": [
          "parseSuccessfulResponse"
        ],
        "procedures": [
          "sp_WorkOrders_GetLegoLookupSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/work-orders/{recordId:guid}/status-transitions",
        "browserFunctions": [
          "getWorkOrderStatusTransitions"
        ],
        "parsers": [
          "parseSuccessfulResponse"
        ],
        "procedures": [
          "sp_WorkOrders_GetStatusTransitionsSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/work-orders",
        "browserFunctions": [
          "listWorkOrders"
        ],
        "parsers": [
          "parseWorkOrderList"
        ],
        "procedures": [
          "sp_WorkOrders_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/work-orders/{recordId:guid}",
        "browserFunctions": [
          "getWorkOrder"
        ],
        "parsers": [
          "parseWorkOrderDetail"
        ],
        "procedures": [
          "sp_WorkOrders_GetSecured",
          "sp_Tenant_RecordDynamicFields_GetSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/work-orders",
        "browserFunctions": [
          "createWorkOrder"
        ],
        "parsers": [
          "parseWorkOrderMutation"
        ],
        "procedures": [
          "sp_WorkOrders_CreateWithDynamicFieldsSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/work-orders/{recordId:guid}",
        "browserFunctions": [
          "updateWorkOrder"
        ],
        "parsers": [
          "parseWorkOrderMutation"
        ],
        "procedures": [
          "sp_WorkOrders_GetSecured",
          "sp_WorkOrders_UpdateWithDynamicFieldsSecured",
          "sp_RecordScope_GetCurrentSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/work-orders/{recordId:guid}",
        "browserFunctions": [
          "removeWorkOrder"
        ],
        "parsers": [
          "parseWorkOrderRemoval"
        ],
        "procedures": [
          "sp_WorkOrders_GetSecured",
          "sp_WorkOrders_RemoveSecured",
          "sp_RecordScope_GetCurrentSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/work-orders/{recordId:guid}/status",
        "browserFunctions": [
          "setWorkOrderStatus"
        ],
        "parsers": [
          "parseWorkOrderMutation"
        ],
        "procedures": [
          "sp_WorkOrders_GetSecured",
          "sp_WorkOrders_SetStatusSecured",
          "sp_RecordScope_GetCurrentSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/work-orders/{recordId:guid}/assignment",
        "browserFunctions": [
          "assignWorkOrder"
        ],
        "parsers": [
          "parseWorkOrderMutation"
        ],
        "procedures": [
          "sp_WorkOrders_GetSecured",
          "sp_WorkOrders_AssignSecured",
          "sp_RecordScope_GetCurrentSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/work-orders/export/capability",
        "browserFunctions": [
          "getWorkOrderExportCapability"
        ],
        "parsers": [
          "parseModuleExportCapability"
        ],
        "procedures": [
          "sp_WorkOrders_GetExportCapabilitySecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/work-orders/export",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_WorkOrders_ExportSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "reservations",
    "title": "Reservations",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.reservations",
    "apiBasePaths": [
      "/api/modules/reservations"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/reservations/products",
        "browserFunctions": [
          "listReservationProducts"
        ],
        "parsers": [
          "parseReservationProductList"
        ],
        "procedures": [
          "sp_ReservationProducts_ListSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/reservations/products",
        "browserFunctions": [
          "saveReservationProduct"
        ],
        "parsers": [
          "parseReservationMutation"
        ],
        "procedures": [
          "sp_ReservationProducts_UpsertSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/reservations",
        "browserFunctions": [
          "listReservations"
        ],
        "parsers": [
          "parseReservationList"
        ],
        "procedures": [
          "sp_Reservations_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/reservations/assignees",
        "browserFunctions": [
          "listReservationAssignees"
        ],
        "parsers": [
          "parseReservationAssigneeLookup"
        ],
        "procedures": [
          "sp_Reservations_GetAssigneesSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/reservations/capabilities",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Runtime_GetModuleCapabilitiesSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/reservations/{recordId:guid}",
        "browserFunctions": [
          "getReservation"
        ],
        "parsers": [
          "parseReservationDetail"
        ],
        "procedures": [
          "sp_Reservations_GetSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/reservations/purchase",
        "browserFunctions": [
          "purchaseReservation"
        ],
        "parsers": [
          "parseReservationMutation"
        ],
        "procedures": [
          "sp_Reservations_PurchaseSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/reservations/{recordId:guid}/status",
        "browserFunctions": [
          "setReservationStatus"
        ],
        "parsers": [
          "parseReservationMutation"
        ],
        "procedures": [
          "sp_Reservations_SetStatusSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/reservations/{recordId:guid}/schedule",
        "browserFunctions": [
          "rescheduleReservation"
        ],
        "parsers": [
          "parseReservationMutation"
        ],
        "procedures": [
          "sp_Reservations_RescheduleSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/reservations/{recordId:guid}/custom-fields",
        "browserFunctions": [
          "updateReservationCustomFields"
        ],
        "parsers": [
          "parseReservationMutation"
        ],
        "procedures": [
          "sp_Reservations_UpdateCustomFieldsSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/reservations/{recordId:guid}/followups",
        "browserFunctions": [
          "updateReservationFollowup"
        ],
        "parsers": [
          "parseReservationMutation"
        ],
        "procedures": [
          "sp_ReservationFollowups_UpdateSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/reservations/lego/catalog",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      },
      {
        "method": "GET",
        "route": "/api/modules/reservations/export/capability",
        "browserFunctions": [
          "getReservationExportCapability"
        ],
        "parsers": [
          "parseModuleExportCapability"
        ],
        "procedures": [
          "sp_Reservations_GetExportCapabilitySecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/reservations/export",
        "browserFunctions": [
          "exportReservations"
        ],
        "parsers": [],
        "procedures": [
          "sp_Reservations_ExportSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "calendar",
    "title": "Calendar",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.calendar",
    "apiBasePaths": [
      "/api/modules/calendar"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/calendar",
        "browserFunctions": [
          "listCalendarEvents"
        ],
        "parsers": [
          "parseCalendarEventList"
        ],
        "procedures": [
          "sp_Calendar_ListSecured",
          "sp_Calendar_CreateSecured",
          "sp_Calendar_UpdateSecured",
          "sp_Developer_DeleteRecord",
          "sp_Calendar_SetFavoriteSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/calendar/{recordId:guid}",
        "browserFunctions": [
          "getCalendarEvent"
        ],
        "parsers": [
          "parseCalendarEventDetail"
        ],
        "procedures": [
          "sp_Calendar_GetSecured",
          "sp_Calendar_CreateSecured",
          "sp_Calendar_UpdateSecured",
          "sp_Developer_DeleteRecord",
          "sp_Calendar_SetFavoriteSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/calendar",
        "browserFunctions": [
          "createCalendarEvent"
        ],
        "parsers": [
          "parseCalendarMutation"
        ],
        "procedures": [
          "WriteAuditLog",
          "sp_Calendar_CreateSecured",
          "sp_Calendar_UpdateSecured",
          "sp_Developer_DeleteRecord",
          "sp_Calendar_SetFavoriteSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/calendar/{recordId:guid}",
        "browserFunctions": [
          "updateCalendarEvent"
        ],
        "parsers": [
          "parseCalendarMutation"
        ],
        "procedures": [
          "WriteAuditLog",
          "sp_Calendar_CreateSecured",
          "sp_Calendar_UpdateSecured",
          "sp_Developer_DeleteRecord",
          "sp_Calendar_SetFavoriteSecured",
          "sp_RecordScope_GetCurrentSecured",
          "sp_Calendar_GetSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/calendar/capabilities",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Calendar_CreateSecured",
          "sp_Calendar_UpdateSecured",
          "sp_Developer_DeleteRecord",
          "sp_Calendar_SetFavoriteSecured",
          "sp_Runtime_GetModuleCapabilitiesSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/calendar/{recordId:guid}",
        "browserFunctions": [
          "removeCalendarEvent"
        ],
        "parsers": [
          "parseCalendarRemoval"
        ],
        "procedures": [
          "sp_Calendar_CreateSecured",
          "sp_Calendar_UpdateSecured",
          "sp_Developer_DeleteRecord",
          "sp_Calendar_SetFavoriteSecured",
          "sp_RecordScope_GetCurrentSecured",
          "sp_Calendar_GetSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/calendar/{recordId:guid}/favorite",
        "browserFunctions": [
          "setCalendarFavorite"
        ],
        "parsers": [
          "parseCalendarMutation"
        ],
        "procedures": [
          "sp_Calendar_CreateSecured",
          "sp_Calendar_UpdateSecured",
          "sp_Developer_DeleteRecord",
          "sp_Calendar_SetFavoriteSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/calendar/lego/catalog",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "files",
    "title": "Files",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.files",
    "apiBasePaths": [
      "/api/modules/files"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/files",
        "browserFunctions": [
          "listFiles"
        ],
        "parsers": [
          "parseFileList"
        ],
        "procedures": [
          "sp_Files_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/files/capabilities",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Runtime_GetModuleCapabilitiesSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/files/personal-limit",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_FileStorage_GetPersonalFileLimitSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/files/personal-limit",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_FileStorage_SaveOrganizationPersonalFileLimitSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/files/{recordId:guid}",
        "browserFunctions": [
          "getFile"
        ],
        "parsers": [
          "parseFileDetail"
        ],
        "procedures": [
          "sp_Files_GetSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/files/upload",
        "browserFunctions": [
          "uploadFile"
        ],
        "parsers": [
          "parseFileMutation"
        ],
        "procedures": [
          "sp_FileStorage_ReserveFilesUploadSecured",
          "sp_FileStorage_CommitFilesUploadSecured",
          "sp_FileStorage_RetireFilesUploadSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/files/{recordId:guid}",
        "browserFunctions": [
          "updateFile"
        ],
        "parsers": [
          "parseFileMutation"
        ],
        "procedures": [
          "sp_Files_UpdateSecured",
          "WriteAuditLog"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/files/{recordId:guid}",
        "browserFunctions": [
          "removeFile"
        ],
        "parsers": [
          "parseFileRemoval"
        ],
        "procedures": [
          "sp_Files_RemoveSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/files/{recordId:guid}/attachments",
        "browserFunctions": [
          "attachFile"
        ],
        "parsers": [
          "parseFileMutation"
        ],
        "procedures": [
          "sp_Files_AttachSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/files/{recordId:guid}/attachments/{attachmentId:guid}",
        "browserFunctions": [
          "detachFile"
        ],
        "parsers": [
          "parseFileMutation"
        ],
        "procedures": [
          "sp_Files_DetachSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/files/{recordId:guid}/favorite",
        "browserFunctions": [
          "setFileFavorite"
        ],
        "parsers": [
          "parseFileMutation"
        ],
        "procedures": [
          "sp_Files_SetFavoriteSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/files/{recordId:guid}/comments",
        "browserFunctions": [
          "listFileComments"
        ],
        "parsers": [
          "parseFileCommentPage"
        ],
        "procedures": [
          "sp_Documents_ListCommentsSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/files/{recordId:guid}/comments",
        "browserFunctions": [
          "addFileComment"
        ],
        "parsers": [
          "parseFileCommentReceipt"
        ],
        "procedures": [
          "sp_Documents_AddCommentSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/files/{recordId:guid}/comments/{commentId:guid}",
        "browserFunctions": [
          "removeFileComment"
        ],
        "parsers": [
          "parseFileCommentRemoval"
        ],
        "procedures": [
          "sp_Documents_RemoveCommentSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/files/lego/catalog",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      },
      {
        "method": "GET",
        "route": "/api/modules/files/{recordId:guid}/content",
        "browserFunctions": [
          "downloadFileContent"
        ],
        "parsers": [],
        "procedures": [
          "sp_Files_GetDownloadSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/files/{recordId:guid}/versions",
        "browserFunctions": [
          "uploadFileVersion"
        ],
        "parsers": [
          "parseFileMutation"
        ],
        "procedures": [
          "sp_FileStorage_RetireFilesUploadSecured",
          "sp_FileStorage_ReserveFileVersionUploadSecured",
          "sp_FileStorage_CommitFileVersionUploadSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/files/{recordId:guid}/versions",
        "browserFunctions": [
          "listFileVersions"
        ],
        "parsers": [
          "parseFileVersionPage"
        ],
        "procedures": [
          "sp_Files_ListVersionsSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/files/{recordId:guid}/versions/{version:int}/content",
        "browserFunctions": [
          "downloadFileVersionContent"
        ],
        "parsers": [],
        "procedures": [
          "sp_Files_GetVersionDownloadSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/tenant/native-message-attachments/{recordId:guid}/content",
        "browserFunctions": [
          "downloadNativeMessageAttachment"
        ],
        "parsers": [],
        "procedures": [
          "sp_NativeMessageAttachments_GetDownloadSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "conversations",
    "title": "Conversations",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.conversations",
    "apiBasePaths": [
      "/api/modules/conversations"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/conversations",
        "browserFunctions": [
          "listConversations"
        ],
        "parsers": [
          "parseConversationList"
        ],
        "procedures": [
          "sp_Conversations_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/conversations/{recordId:guid}",
        "browserFunctions": [
          "getConversation"
        ],
        "parsers": [
          "parseConversationDetail"
        ],
        "procedures": [
          "sp_Conversations_GetSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/conversations/{recordId:guid}/messages/{messageId:guid}/attachments/{fileId:guid}/content",
        "browserFunctions": [
          "downloadConversationAttachment"
        ],
        "parsers": [],
        "procedures": [
          "sp_Conversations_GetAttachmentDownloadSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/conversations",
        "browserFunctions": [
          "createConversation"
        ],
        "parsers": [
          "parseConversationMutation"
        ],
        "procedures": [
          "WriteAuditLog",
          "sp_Conversations_CreateSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/conversations/{recordId:guid}",
        "browserFunctions": [
          "updateConversation"
        ],
        "parsers": [
          "parseConversationMutation"
        ],
        "procedures": [
          "WriteAuditLog",
          "sp_Conversations_UpdateSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/conversations/lego-catalog",
        "browserFunctions": [
          "getConversationsLegoCatalog"
        ],
        "parsers": [
          "parseSuccessfulResponse"
        ],
        "procedures": []
      },
      {
        "method": "GET",
        "route": "/api/modules/conversations/lego-presentation",
        "browserFunctions": [
          "getConversationsLegoPresentation"
        ],
        "parsers": [
          "parseSuccessfulResponse"
        ],
        "procedures": [
          "sp_Conversations_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/conversations/capabilities",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Runtime_GetModuleCapabilitiesSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/conversations/{recordId:guid}",
        "browserFunctions": [
          "removeConversation"
        ],
        "parsers": [
          "parseConversationRemoval"
        ],
        "procedures": [
          "sp_Conversations_DeleteSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/conversations/{recordId:guid}/messages",
        "browserFunctions": [
          "postConversationMessage"
        ],
        "parsers": [
          "parseConversationMutation"
        ],
        "procedures": [
          "WriteAuditLog",
          "sp_Conversations_ReplySecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/conversations/direct/scope",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Conversations_GetDirectScopeSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/conversations/direct",
        "browserFunctions": [
          "sendDirectConversation"
        ],
        "parsers": [
          "parseConversationMutation"
        ],
        "procedures": [
          "sp_Conversations_SendDirectSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/conversations/{recordId:guid}/favorite",
        "browserFunctions": [
          "setConversationFavorite"
        ],
        "parsers": [
          "parseConversationMutation"
        ],
        "procedures": [
          "sp_Conversations_SetFavoriteSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "company-news",
    "title": "Company news",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.company-news",
    "apiBasePaths": [
      "/api/modules/company-news"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/company-news/schema",
        "browserFunctions": [
          "getCompanyNewsLegoCatalog"
        ],
        "parsers": [
          "parseSuccessfulResponse"
        ],
        "procedures": [
          "sp_CompanyNews_GetLegoCatalogSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/company-news/lookups/{lookupId:guid}",
        "browserFunctions": [
          "getCompanyNewsLegoLookup"
        ],
        "parsers": [
          "parseSuccessfulResponse"
        ],
        "procedures": [
          "sp_CompanyNews_GetLegoLookupSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/company-news",
        "browserFunctions": [
          "listCompanyNews"
        ],
        "parsers": [
          "parseCompanyNewsList"
        ],
        "procedures": [
          "sp_CompanyNews_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/company-news/{recordId:guid}",
        "browserFunctions": [
          "getCompanyNews"
        ],
        "parsers": [
          "parseCompanyNewsDetail"
        ],
        "procedures": [
          "sp_CompanyNews_GetSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/company-news",
        "browserFunctions": [
          "createCompanyNews"
        ],
        "parsers": [
          "parseCompanyNewsMutation"
        ],
        "procedures": [
          "sp_CompanyNews_CreateSecured",
          "WriteAuditLog"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/company-news/{recordId:guid}",
        "browserFunctions": [
          "updateCompanyNews"
        ],
        "parsers": [
          "parseCompanyNewsMutation"
        ],
        "procedures": [
          "sp_CompanyNews_UpdateSecured",
          "WriteAuditLog"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/company-news/{recordId:guid}/favorite",
        "browserFunctions": [
          "setCompanyNewsFavorite"
        ],
        "parsers": [
          "parseCompanyNewsMutation"
        ],
        "procedures": [
          "sp_CompanyNews_SetFavoriteSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/company-news/{recordId:guid}/published",
        "browserFunctions": [
          "setCompanyNewsPublished"
        ],
        "parsers": [
          "parseCompanyNewsMutation"
        ],
        "procedures": [
          "sp_CompanyNews_SetPublishedSecured",
          "WriteAuditLog"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/company-news/{recordId:guid}",
        "browserFunctions": [
          "removeCompanyNews"
        ],
        "parsers": [
          "parseCompanyNewsRemoval"
        ],
        "procedures": [
          "sp_CompanyNews_RemoveSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "knowledge-core",
    "title": "Knowledge Core",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.knowledge-articles",
    "apiBasePaths": [
      "/api/modules/knowledge-articles",
      "/api/modules/knowledge-core"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/knowledge-articles",
        "browserFunctions": [
          "listKnowledgeArticles"
        ],
        "parsers": [
          "parseKnowledgeArticlesList"
        ],
        "procedures": [
          "sp_KnowledgeArticles_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-articles/{recordId:guid}",
        "browserFunctions": [
          "getKnowledgeArticle"
        ],
        "parsers": [
          "parseKnowledgeArticleDetail"
        ],
        "procedures": [
          "sp_KnowledgeArticles_GetSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-articles",
        "browserFunctions": [
          "createKnowledgeArticle"
        ],
        "parsers": [
          "parseKnowledgeArticleMutation"
        ],
        "procedures": [
          "sp_KnowledgeArticles_CreateSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/knowledge-articles/{recordId:guid}",
        "browserFunctions": [
          "updateKnowledgeArticle"
        ],
        "parsers": [
          "parseKnowledgeArticleMutation"
        ],
        "procedures": [
          "sp_KnowledgeArticles_UpdateSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/knowledge-articles/{recordId:guid}/favorite",
        "browserFunctions": [
          "setKnowledgeArticleFavorite"
        ],
        "parsers": [
          "parseKnowledgeArticleMutation"
        ],
        "procedures": [
          "sp_KnowledgeArticles_SetFavoriteSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/knowledge-articles/{recordId:guid}",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_KnowledgeArticles_RemoveSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-articles/lego/catalog",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core",
        "browserFunctions": [
          "listKnowledgeCore"
        ],
        "parsers": [
          "parseKnowledgeCoreList"
        ],
        "procedures": [
          "sp_kc_ListKnowledgeItemsSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core/{recordId:guid}",
        "browserFunctions": [
          "getKnowledgeCore"
        ],
        "parsers": [
          "parseKnowledgeCoreDetail"
        ],
        "procedures": [
          "sp_kc_GetKnowledgeItemSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core",
        "browserFunctions": [
          "createKnowledgeCore"
        ],
        "parsers": [
          "parseKnowledgeCoreMutation"
        ],
        "procedures": [
          "sp_kc_CreateKnowledgeItem"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/knowledge-core/{recordId:guid}",
        "browserFunctions": [
          "updateKnowledgeCore"
        ],
        "parsers": [
          "parseKnowledgeCoreMutation"
        ],
        "procedures": [
          "sp_kc_UpdateKnowledgeItem"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/{recordId:guid}/publish",
        "browserFunctions": [
          "publishKnowledgeCore"
        ],
        "parsers": [
          "parseKnowledgeCoreMutation"
        ],
        "procedures": [
          "sp_kc_PublishKnowledgeItem"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/{recordId:guid}/archive",
        "browserFunctions": [
          "archiveKnowledgeCore"
        ],
        "parsers": [
          "parseKnowledgeCoreMutation"
        ],
        "procedures": [
          "sp_kc_ArchiveKnowledgeItem"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core/{recordId:guid}/revisions",
        "browserFunctions": [
          "getKnowledgeCoreRevisions"
        ],
        "parsers": [
          "parseKnowledgeRevisions"
        ],
        "procedures": [
          "sp_kc_GetRevisionHistorySecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/{recordId:guid}/restore",
        "browserFunctions": [
          "restoreKnowledgeCoreRevision"
        ],
        "parsers": [
          "parseKnowledgeCoreMutation"
        ],
        "procedures": [
          "sp_kc_RestoreRevisionAsDraft"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core/collections",
        "browserFunctions": [
          "listKnowledgeCoreCollections"
        ],
        "parsers": [
          "parseKnowledgeCollections"
        ],
        "procedures": [
          "sp_kc_ListCollectionsSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/collections",
        "browserFunctions": [
          "createKnowledgeCoreCollection"
        ],
        "parsers": [
          "parseKnowledgeCollectionMutation"
        ],
        "procedures": [
          "sp_kc_CreateCollection"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/knowledge-core/collections/{collectionId:guid}",
        "browserFunctions": [
          "updateKnowledgeCoreCollection"
        ],
        "parsers": [
          "parseKnowledgeCollectionMutation"
        ],
        "procedures": [
          "sp_kc_UpdateCollection"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/collections/{collectionId:guid}/items/{recordId:guid}",
        "browserFunctions": [
          "addKnowledgeCoreCollectionItem"
        ],
        "parsers": [
          "parseKnowledgeCollectionMutation"
        ],
        "procedures": [
          "sp_kc_AddKnowledgeItemToCollection"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/knowledge-core/collections/{collectionId:guid}/items/{recordId:guid}",
        "browserFunctions": [
          "removeKnowledgeCoreCollectionItem"
        ],
        "parsers": [
          "parseKnowledgeCollectionMutation"
        ],
        "procedures": [
          "sp_kc_RemoveKnowledgeItemFromCollection"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core/{recordId:guid}/owners",
        "browserFunctions": [
          "getKnowledgeCoreOwners"
        ],
        "parsers": [
          "parseKnowledgeOwners"
        ],
        "procedures": [
          "sp_kc_GetKnowledgeOwnersSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/{recordId:guid}/owners",
        "browserFunctions": [
          "setKnowledgeCoreOwner"
        ],
        "parsers": [
          "parseKnowledgeOwnerMutation"
        ],
        "procedures": [
          "sp_kc_SetKnowledgeOwner"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/knowledge-core/owners/{knowledgeOwnerId:guid}",
        "browserFunctions": [
          "removeKnowledgeCoreOwner"
        ],
        "parsers": [
          "parseKnowledgeOwnerMutation"
        ],
        "procedures": [
          "sp_kc_RemoveKnowledgeOwner"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core/unowned",
        "browserFunctions": [
          "listUnownedKnowledgeCore"
        ],
        "parsers": [
          "parseKnowledgeCoreList"
        ],
        "procedures": [
          "sp_kc_GetUnownedKnowledgeSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core/assignment-lookup",
        "browserFunctions": [
          "getKnowledgeAssignmentLookup"
        ],
        "parsers": [
          "parseKnowledgeAssignmentLookup"
        ],
        "procedures": [
          "sp_kc_GetAssignmentLookupSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core/reviews",
        "browserFunctions": [
          "listKnowledgeReviews"
        ],
        "parsers": [
          "parseKnowledgeReviews"
        ],
        "procedures": [
          "sp_kc_ListDueReviewsSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/begin",
        "browserFunctions": [
          "beginKnowledgeReview"
        ],
        "parsers": [
          "parseKnowledgeReviewMutation"
        ],
        "procedures": [
          "sp_kc_BeginReview"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/complete",
        "browserFunctions": [
          "completeKnowledgeReview"
        ],
        "parsers": [
          "parseKnowledgeReviewMutation"
        ],
        "procedures": [
          "sp_kc_CompleteReview"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/reassign",
        "browserFunctions": [
          "reassignKnowledgeReview"
        ],
        "parsers": [
          "parseKnowledgeReviewMutation"
        ],
        "procedures": [
          "sp_kc_ReassignReview"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core/health",
        "browserFunctions": [
          "getKnowledgeHealth"
        ],
        "parsers": [
          "parseKnowledgeHealth"
        ],
        "procedures": [
          "sp_kc_GetKnowledgeHealthSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core/questions",
        "browserFunctions": [
          "listKnowledgeQuestions"
        ],
        "parsers": [
          "parseKnowledgeQuestions"
        ],
        "procedures": [
          "sp_kc_GetOpenQuestionsSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/questions",
        "browserFunctions": [
          "createKnowledgeQuestion"
        ],
        "parsers": [
          "parseKnowledgeQuestionMutation"
        ],
        "procedures": [
          "sp_kc_CreateQuestion"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_kc_MutateQuestionSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/close",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_kc_MutateQuestionSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/assign",
        "browserFunctions": [
          "assignKnowledgeQuestion"
        ],
        "parsers": [
          "parseKnowledgeQuestionMutation"
        ],
        "procedures": [
          "sp_kc_AssignQuestion"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/answer",
        "browserFunctions": [
          "answerKnowledgeQuestion"
        ],
        "parsers": [
          "parseKnowledgeQuestionMutation"
        ],
        "procedures": [
          "sp_kc_AnswerQuestion"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/convert",
        "browserFunctions": [
          "convertKnowledgeQuestion"
        ],
        "parsers": [
          "parseKnowledgeQuestionMutation"
        ],
        "procedures": [
          "sp_kc_ConvertQuestionToKnowledge"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/{recordId:guid}/feedback",
        "browserFunctions": [
          "recordKnowledgeFeedback"
        ],
        "parsers": [
          "parseKnowledgeFeedbackMutation"
        ],
        "procedures": [
          "sp_kc_RecordFeedback"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core/{recordId:guid}/feedback",
        "browserFunctions": [
          "getKnowledgeFeedback"
        ],
        "parsers": [
          "parseKnowledgeFeedbackSummary"
        ],
        "procedures": [
          "sp_kc_GetKnowledgeFeedbackSummarySecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core/{recordId:guid}/feedback/comments",
        "browserFunctions": [
          "listKnowledgeFeedbackComments"
        ],
        "parsers": [
          "parseKnowledgeFeedbackCommentPage"
        ],
        "procedures": [
          "sp_kc_ListFeedbackCommentsSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core/gaps",
        "browserFunctions": [
          "getKnowledgeGaps"
        ],
        "parsers": [
          "parseKnowledgeGaps"
        ],
        "procedures": [
          "sp_kc_GetKnowledgeGapsSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/knowledge-core/support-learning/candidates",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_kc_GetSupportLearningCandidatesSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/knowledge-core/support-learning/candidates",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_kc_CreateSupportResolutionCandidate"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "web-links",
    "title": "Web links",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.web-links",
    "apiBasePaths": [
      "/api/modules/web-links"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/web-links/lego/catalog",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      },
      {
        "method": "GET",
        "route": "/api/modules/web-links/lookups/{lookupId:guid}",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      },
      {
        "method": "GET",
        "route": "/api/modules/web-links",
        "browserFunctions": [
          "listWebLinks"
        ],
        "parsers": [
          "parseWebLinksList"
        ],
        "procedures": [
          "sp_WebLinks_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/web-links/{recordId:guid}",
        "browserFunctions": [
          "getWebLink"
        ],
        "parsers": [
          "parseWebLinkDetail"
        ],
        "procedures": [
          "sp_WebLinks_GetSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/web-links",
        "browserFunctions": [
          "createWebLink"
        ],
        "parsers": [
          "parseWebLinkMutation"
        ],
        "procedures": [
          "sp_WebLinks_CreateSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/web-links/{recordId:guid}",
        "browserFunctions": [
          "updateWebLink"
        ],
        "parsers": [
          "parseWebLinkMutation"
        ],
        "procedures": [
          "sp_WebLinks_UpdateSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/web-links/{recordId:guid}",
        "browserFunctions": [
          "removeWebLink"
        ],
        "parsers": [
          "parseWebLinkRemoval"
        ],
        "procedures": [
          "sp_WebLinks_GetSecured",
          "sp_Developer_DeleteRecord"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/web-links/{recordId:guid}/favorite",
        "browserFunctions": [
          "setWebLinkFavorite"
        ],
        "parsers": [
          "parseWebLinkMutation"
        ],
        "procedures": [
          "sp_WebLinks_SetFavoriteSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "chat-rooms",
    "title": "Chat rooms",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.chat-rooms",
    "apiBasePaths": [
      "/api/modules/chat-rooms"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/chat-rooms",
        "browserFunctions": [
          "listChatRooms"
        ],
        "parsers": [
          "parseChatRoomsList"
        ],
        "procedures": [
          "sp_ChatRooms_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/chat-rooms/{recordId:guid}",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_ChatRooms_GetSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/chat-rooms",
        "browserFunctions": [
          "createChatRoom"
        ],
        "parsers": [
          "parseChatRoomMutation"
        ],
        "procedures": [
          "WriteAuditLog",
          "sp_ChatRooms_CreateSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/chat-rooms/{recordId:guid}",
        "browserFunctions": [
          "updateChatRoom"
        ],
        "parsers": [
          "parseChatRoomMutation"
        ],
        "procedures": [
          "WriteAuditLog",
          "sp_ChatRooms_UpdateSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/chat-rooms/lego/catalog",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      },
      {
        "method": "DELETE",
        "route": "/api/modules/chat-rooms/{recordId:guid}",
        "browserFunctions": [
          "removeChatRoom"
        ],
        "parsers": [
          "parseChatRoomRemoval"
        ],
        "procedures": [
          "sp_ChatRooms_DeleteSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/chat-rooms/{recordId:guid}/messages",
        "browserFunctions": [
          "postChatMessage"
        ],
        "parsers": [
          "parseChatRoomMutation"
        ],
        "procedures": [
          "WriteAuditLog",
          "sp_ChatRooms_PostMessageSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/chat-rooms/{recordId:guid}/messages/{chatMessageId:guid}",
        "browserFunctions": [
          "updateChatMessage"
        ],
        "parsers": [
          "parseChatRoomMutation"
        ],
        "procedures": [
          "WriteAuditLog",
          "sp_ChatRooms_UpdateMessageSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/chat-rooms/{recordId:guid}/messages/{chatMessageId:guid}",
        "browserFunctions": [
          "removeChatMessage"
        ],
        "parsers": [
          "parseChatRoomMutation"
        ],
        "procedures": [
          "WriteAuditLog",
          "sp_ChatRooms_DeleteMessageSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/chat-rooms/{recordId:guid}/messages/{chatMessageId:guid}/reaction",
        "browserFunctions": [
          "setChatReaction"
        ],
        "parsers": [
          "parseChatRoomMutation"
        ],
        "procedures": [
          "sp_ChatRooms_SetReactionSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/chat-rooms/{recordId:guid}/members/{memberUserId:guid}",
        "browserFunctions": [
          "setChatRoomMember"
        ],
        "parsers": [
          "parseChatRoomMutation"
        ],
        "procedures": [
          "sp_ChatRooms_SetMemberSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/chat-rooms/{recordId:guid}/members/lookup",
        "browserFunctions": [
          "getChatRoomMemberLookup"
        ],
        "parsers": [
          "parseChatRoomMemberLookup"
        ],
        "procedures": [
          "sp_ChatRooms_GetMemberLookupSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/chat-rooms/{recordId:guid}/read",
        "browserFunctions": [
          "markChatRoomRead"
        ],
        "parsers": [
          "parseChatRoomMutation"
        ],
        "procedures": [
          "sp_ChatRooms_MarkReadSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/chat-rooms/{recordId:guid}/favorite",
        "browserFunctions": [
          "setChatRoomFavorite"
        ],
        "parsers": [
          "parseChatRoomMutation"
        ],
        "procedures": [
          "sp_ChatRooms_SetFavoriteSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "discussion-boards",
    "title": "Discussion Boards",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.discussion-boards",
    "apiBasePaths": [
      "/api/modules/discussion-boards"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/discussion-boards",
        "browserFunctions": [
          "listDiscussionBoards"
        ],
        "parsers": [
          "parseDiscussionBoardsList"
        ],
        "procedures": [
          "sp_DiscussionBoards_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/discussion-boards/{recordId:guid}",
        "browserFunctions": [
          "getDiscussionBoard"
        ],
        "parsers": [
          "parseDiscussionBoardDetail"
        ],
        "procedures": [
          "sp_DiscussionBoards_GetBoardSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/discussion-boards",
        "browserFunctions": [
          "createDiscussionBoard"
        ],
        "parsers": [
          "parseDiscussionMutation"
        ],
        "procedures": [
          "sp_DiscussionBoards_CreateBoardSecured",
          "WriteAuditLog"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/discussion-boards/{recordId:guid}",
        "browserFunctions": [
          "updateDiscussionBoard"
        ],
        "parsers": [
          "parseDiscussionMutation"
        ],
        "procedures": [
          "sp_DiscussionBoards_UpdateBoardSecured",
          "WriteAuditLog"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/discussion-boards/lego/catalog",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      },
      {
        "method": "DELETE",
        "route": "/api/modules/discussion-boards/{recordId:guid}",
        "browserFunctions": [
          "removeDiscussionBoard"
        ],
        "parsers": [
          "parseDiscussionBoardRemoval"
        ],
        "procedures": [
          "sp_DiscussionBoards_DeleteBoardSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/discussion-boards/{boardRecordId:guid}/topics",
        "browserFunctions": [
          "createDiscussionTopic"
        ],
        "parsers": [
          "parseDiscussionMutation"
        ],
        "procedures": [
          "sp_DiscussionBoards_CreateTopicSecured",
          "WriteAuditLog"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/discussion-boards/topics/{recordId:guid}",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_DiscussionBoards_GetTopicSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/discussion-boards/topics/{recordId:guid}",
        "browserFunctions": [
          "updateDiscussionTopic"
        ],
        "parsers": [
          "parseDiscussionMutation"
        ],
        "procedures": [
          "sp_DiscussionBoards_UpdateTopicSecured",
          "WriteAuditLog"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/discussion-boards/topics/{recordId:guid}",
        "browserFunctions": [
          "removeDiscussionTopic"
        ],
        "parsers": [
          "parseDiscussionTopicRemoval"
        ],
        "procedures": [
          "sp_DiscussionBoards_DeleteTopicSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/discussion-boards/topics/{topicRecordId:guid}/posts",
        "browserFunctions": [
          "postDiscussionReply"
        ],
        "parsers": [
          "parseDiscussionMutation"
        ],
        "procedures": [
          "sp_DiscussionBoards_PostReplySecured",
          "WriteAuditLog"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/discussion-boards/posts/{recordId:guid}",
        "browserFunctions": [
          "updateDiscussionPost"
        ],
        "parsers": [
          "parseDiscussionMutation"
        ],
        "procedures": [
          "sp_DiscussionBoards_UpdatePostSecured",
          "WriteAuditLog"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/discussion-boards/posts/{recordId:guid}",
        "browserFunctions": [
          "removeDiscussionPost"
        ],
        "parsers": [
          "parseDiscussionPostRemoval"
        ],
        "procedures": [
          "sp_DiscussionBoards_DeletePostSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/discussion-boards/records/{recordId:guid}/favorite",
        "browserFunctions": [
          "setDiscussionFavorite"
        ],
        "parsers": [
          "parseDiscussionMutation"
        ],
        "procedures": [
          "sp_DiscussionBoards_SetFavoriteSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "mail-reader",
    "title": "Mail reader",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.mail-reader",
    "apiBasePaths": [
      "/api/modules/mail-reader"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/mail-reader",
        "browserFunctions": [
          "listMailReaderMessages"
        ],
        "parsers": [
          "parseMailReaderList"
        ],
        "procedures": [
          "sp_MailReader_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/mail-reader/{recordId:guid}",
        "browserFunctions": [
          "getMailReaderMessage"
        ],
        "parsers": [
          "parseMailReaderDetail"
        ],
        "procedures": [
          "sp_MailReader_GetSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/mail-reader/{recordId:guid}/read",
        "browserFunctions": [
          "setMailReaderRead"
        ],
        "parsers": [],
        "procedures": [
          "sp_MailReader_SetReadSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/mail-reader/{recordId:guid}/archive",
        "browserFunctions": [
          "archiveMailReaderMessage"
        ],
        "parsers": [],
        "procedures": [
          "sp_MailReader_ArchiveSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/mail-reader/mailboxes",
        "browserFunctions": [
          "listMailReaderMailboxes"
        ],
        "parsers": [
          "parseMailReaderMailboxes"
        ],
        "procedures": [
          "sp_MailReader_ListMailboxesSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/mail-reader/mailboxes",
        "browserFunctions": [
          "createMailReaderMailbox"
        ],
        "parsers": [
          "parseMailReaderMailboxMutation"
        ],
        "procedures": [
          "sp_MailReader_CreateMailboxSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/mail-reader/mailboxes/{mailboxId:guid}",
        "browserFunctions": [
          "updateMailReaderMailbox"
        ],
        "parsers": [
          "parseMailReaderMailboxMutation"
        ],
        "procedures": [
          "sp_MailReader_UpdateMailboxSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/mail-reader/{recordId:guid}/favorite",
        "browserFunctions": [
          "setMailReaderFavorite"
        ],
        "parsers": [],
        "procedures": [
          "sp_MailReader_SetFavoriteSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/mail-reader/mailboxes/{mailboxRecordId:guid}/credentials/{purpose}",
        "browserFunctions": [
          "setMailReaderCredential"
        ],
        "parsers": [
          "parseMailReaderCredentialStatus"
        ],
        "procedures": [
          "sp_MailReader_SetMailboxCredentialSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/mail-reader/mailboxes/{mailboxRecordId:guid}/compose",
        "browserFunctions": [
          "composeMailReaderEmail"
        ],
        "parsers": [
          "parseMailReaderComposeResult"
        ],
        "procedures": [
          "sp_Conversations_CreateSecured",
          "sp_Conversations_ReplySecured",
          "sp_MailReader_ListMailboxesSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "favorites",
    "title": "Favorites",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.favorites",
    "apiBasePaths": [
      "/api/modules/favorites"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/favorites/schema",
        "browserFunctions": [
          "getFavoritesLegoCatalog"
        ],
        "parsers": [
          "parseSuccessfulResponse"
        ],
        "procedures": []
      },
      {
        "method": "GET",
        "route": "/api/modules/favorites/presentation",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Favorites_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/favorites",
        "browserFunctions": [
          "listFavorites"
        ],
        "parsers": [
          "parseFavoritesList"
        ],
        "procedures": [
          "sp_Favorites_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/favorites/{recordId:guid}",
        "browserFunctions": [
          "getFavorite"
        ],
        "parsers": [
          "parseFavoriteDetail"
        ],
        "procedures": [
          "sp_Favorites_GetSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/favorites/{recordId:guid}/state",
        "browserFunctions": [
          "getFavoriteState"
        ],
        "parsers": [
          "parseFavoriteMutation"
        ],
        "procedures": [
          "sp_Favorites_GetStateSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/favorites/{recordId:guid}/favorite",
        "browserFunctions": [
          "setFavorite"
        ],
        "parsers": [
          "parseFavoriteMutation"
        ],
        "procedures": [
          "sp_Favorites_SetSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/favorites/{recordId:guid}/preferences",
        "browserFunctions": [
          "updateFavoritePreferences"
        ],
        "parsers": [
          "parseFavoriteMutation"
        ],
        "procedures": [
          "sp_Favorites_UpdateSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "notifications",
    "title": "Notifications",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.notifications",
    "apiBasePaths": [
      "/api/modules/notifications"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/notifications",
        "browserFunctions": [
          "listNotifications"
        ],
        "parsers": [
          "parseNotificationList"
        ],
        "procedures": [
          "sp_Notifications_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/notifications/lego-catalog",
        "browserFunctions": [
          "getNotificationsLegoCatalog"
        ],
        "parsers": [
          "parseSuccessfulResponse"
        ],
        "procedures": []
      },
      {
        "method": "GET",
        "route": "/api/modules/notifications/lego-presentation",
        "browserFunctions": [
          "getNotificationsLegoPresentation"
        ],
        "parsers": [
          "parseSuccessfulResponse"
        ],
        "procedures": [
          "sp_Notifications_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/notifications/{notificationId:guid}",
        "browserFunctions": [
          "getNotification"
        ],
        "parsers": [
          "parseNotificationDetail"
        ],
        "procedures": [
          "sp_Notifications_GetSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/notifications/{notificationId:guid}/state",
        "browserFunctions": [
          "setNotificationState"
        ],
        "parsers": [
          "parseNotificationMutation"
        ],
        "procedures": [
          "sp_Notifications_SetStateSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/notifications/{notificationId:guid}/source-favorite",
        "browserFunctions": [
          "setNotificationSourceFavorite"
        ],
        "parsers": [
          "parseNotificationMutation"
        ],
        "procedures": [
          "sp_Notifications_SetSourceFavoriteSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "dynamic-records",
    "title": "Dynamic Records",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.dynamic-records",
    "apiBasePaths": [
      "/api/modules/dynamic"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/dynamic",
        "browserFunctions": [
          "listDynamicModuleSchemas"
        ],
        "parsers": [
          "parseDynamicModuleCatalog"
        ],
        "procedures": [
          "sp_DynamicModules_ListSchemasSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/dynamic/{moduleKey}/schema",
        "browserFunctions": [
          "getDynamicModuleSchema"
        ],
        "parsers": [
          "parseDynamicModuleSchema"
        ],
        "procedures": [
          "sp_DynamicModules_GetSchemaSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/dynamic/{moduleKey}/lookups/{lookupId:guid}",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_Checklists_ListRunsSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/dynamic/{moduleKey}/lego/catalog",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_DynamicModules_GetSchemaSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/dynamic/{moduleKey}",
        "browserFunctions": [
          "listDynamicModuleRecords"
        ],
        "parsers": [
          "parseDynamicModuleList"
        ],
        "procedures": [
          "sp_DynamicModules_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/dynamic/{moduleKey}/{recordId:guid}",
        "browserFunctions": [
          "getDynamicModuleRecord"
        ],
        "parsers": [
          "parseDynamicModuleDetail"
        ],
        "procedures": [
          "sp_DynamicModules_GetSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/dynamic/{moduleKey}",
        "browserFunctions": [
          "createDynamicModuleRecord"
        ],
        "parsers": [
          "parseDynamicModuleMutation"
        ],
        "procedures": [
          "sp_DynamicModules_CreateSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/dynamic/{moduleKey}/{recordId:guid}",
        "browserFunctions": [
          "updateDynamicModuleRecord"
        ],
        "parsers": [
          "parseDynamicModuleMutation"
        ],
        "procedures": [
          "sp_DynamicModules_UpdateSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/dynamic/{moduleKey}/{recordId:guid}",
        "browserFunctions": [
          "deleteDynamicModuleRecord"
        ],
        "parsers": [
          "parseDynamicModuleRemoval"
        ],
        "procedures": [
          "sp_Developer_DeleteRecord"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/dynamic/{moduleKey}/{recordId:guid}/favorite",
        "browserFunctions": [
          "setDynamicModuleFavorite"
        ],
        "parsers": [
          "parseDynamicModuleMutation"
        ],
        "procedures": [
          "sp_DynamicModules_SetFavoriteSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/dynamic/caseflow-cases/{recordId:guid}/transition",
        "browserFunctions": [
          "transitionCaseFlowCase"
        ],
        "parsers": [],
        "procedures": [
          "sp_CaseFlow_TransitionSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/dynamic/{moduleKey}/export/capability",
        "browserFunctions": [
          "getDynamicRecordExportCapability"
        ],
        "parsers": [
          "parseModuleExportCapability"
        ],
        "procedures": [
          "sp_DynamicModules_GetExportCapabilitySecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/dynamic/{moduleKey}/export",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_DynamicModules_ExportSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "active-workplace",
    "title": "ActiveWorkplace",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.active-workplace",
    "apiBasePaths": [
      "/api/modules/active-workplace"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/active-workplace",
        "browserFunctions": [
          "listActiveWorkplaces"
        ],
        "parsers": [
          "parseActiveWorkplaceList"
        ],
        "procedures": [
          "sp_ActiveWorkplace_ListSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/active-workplace/lego/catalog",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      },
      {
        "method": "GET",
        "route": "/api/modules/active-workplace/lego/lookups/{lookupId:guid}",
        "browserFunctions": [],
        "parsers": [],
        "procedures": []
      },
      {
        "method": "GET",
        "route": "/api/modules/active-workplace/lego/presentation",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_ActiveWorkplace_ListSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/active-workplace",
        "browserFunctions": [
          "createActiveWorkplace"
        ],
        "parsers": [
          "parseActiveWorkplaceMutation"
        ],
        "procedures": [
          "sp_ActiveWorkplace_CreateWithDynamicFieldsSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/active-workplace/{activeWorkplaceId:guid}",
        "browserFunctions": [
          "getActiveWorkplace"
        ],
        "parsers": [
          "parseActiveWorkplaceDetail"
        ],
        "procedures": [
          "sp_ActiveWorkplace_GetSecured",
          "sp_Tenant_RecordDynamicFields_GetSecured"
        ]
      },
      {
        "method": "PATCH",
        "route": "/api/modules/active-workplace/{activeWorkplaceId:guid}",
        "browserFunctions": [
          "updateActiveWorkplace"
        ],
        "parsers": [
          "parseActiveWorkplaceMutation"
        ],
        "procedures": [
          "sp_ActiveWorkplace_UpdateWithDynamicFieldsSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/active-workplace/{activeWorkplaceId:guid}/status",
        "browserFunctions": [
          "setActiveWorkplaceStatus"
        ],
        "parsers": [
          "parseActiveWorkplaceMutation"
        ],
        "procedures": [
          "sp_ActiveWorkplace_SetStatusSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/active-workplace/{activeWorkplaceId:guid}/participants/catalog",
        "browserFunctions": [
          "getActiveWorkplaceParticipantCatalog"
        ],
        "parsers": [
          "parseActiveWorkplaceCatalog"
        ],
        "procedures": [
          "sp_ActiveWorkplace_GetParticipantCatalogSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/active-workplace/{activeWorkplaceId:guid}/participants",
        "browserFunctions": [
          "addActiveWorkplaceParticipant"
        ],
        "parsers": [
          "parseActiveWorkplaceMutation"
        ],
        "procedures": [
          "sp_ActiveWorkplace_AddParticipantSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/active-workplace/{activeWorkplaceId:guid}/participants/{activeWorkplaceParticipantId:guid}",
        "browserFunctions": [
          "removeActiveWorkplaceParticipant"
        ],
        "parsers": [
          "parseActiveWorkplaceMutation"
        ],
        "procedures": [
          "sp_ActiveWorkplace_RemoveParticipantSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/active-workplace/{activeWorkplaceId:guid}/activity",
        "browserFunctions": [
          "recordActiveWorkplaceActivity"
        ],
        "parsers": [
          "parseActiveWorkplaceMutation"
        ],
        "procedures": [
          "sp_ActiveWorkplace_RecordActivitySecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/active-workplace/{activeWorkplaceId:guid}/graph/refresh",
        "browserFunctions": [
          "refreshActiveWorkplaceGraph"
        ],
        "parsers": [
          "parseActiveWorkplaceMutation"
        ],
        "procedures": [
          "sp_ActiveWorkplace_RefreshGraphSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/active-workplace/{activeWorkplaceId:guid}/playback",
        "browserFunctions": [
          "getActiveWorkplacePlayback"
        ],
        "parsers": [
          "parseActiveWorkplacePlayback"
        ],
        "procedures": [
          "sp_ActiveWorkplace_GetPlaybackSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "record-relations",
    "title": "Record relations",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.record-graph",
    "apiBasePaths": [
      "/api/modules/record-graph"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/record-graph/records",
        "browserFunctions": [
          "searchRecordGraph"
        ],
        "parsers": [
          "parseRecordGraphSearch"
        ],
        "procedures": [
          "sp_RecordGraph_SearchSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/record-graph/{recordId:guid}",
        "browserFunctions": [
          "getRecordGraph"
        ],
        "parsers": [
          "parseRecordGraph"
        ],
        "procedures": [
          "sp_RecordGraph_GetSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/record-graph/{recordId:guid}/relations",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_RecordGraph_ListRelatedSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/record-graph/{recordId:guid}/relations",
        "browserFunctions": [
          "addRecordGraphRelation"
        ],
        "parsers": [
          "parseRecordGraphMutation"
        ],
        "procedures": [
          "sp_RecordGraph_AddRelationSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/record-graph/relations/{recordRelationId:guid}",
        "browserFunctions": [
          "removeRecordGraphRelation"
        ],
        "parsers": [
          "parseRecordGraphMutation"
        ],
        "procedures": [
          "sp_RecordGraph_RemoveRelationSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/record-graph/{recordId:guid}/favorite",
        "browserFunctions": [
          "setRecordGraphFavorite"
        ],
        "parsers": [
          "parseFavoriteMutation"
        ],
        "procedures": [
          "sp_Favorites_SetSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/record-graph/{recordId:guid}/knowledge",
        "browserFunctions": [
          "getRelatedKnowledge"
        ],
        "parsers": [
          "parseRelatedKnowledge"
        ],
        "procedures": [
          "sp_kc_GetRelatedKnowledgeSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/record-graph/{recordId:guid}/knowledge/candidates",
        "browserFunctions": [
          "getContextualKnowledge"
        ],
        "parsers": [
          "parseContextualKnowledge"
        ],
        "procedures": [
          "sp_kc_GetContextualKnowledgeCandidatesSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/record-graph/{recordId:guid}/knowledge",
        "browserFunctions": [
          "linkKnowledgeToRecord"
        ],
        "parsers": [
          "parseKnowledgeRelationMutation"
        ],
        "procedures": [
          "sp_kc_LinkKnowledgeToRecord"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/record-graph/knowledge-relations/{recordRelationId:guid}",
        "browserFunctions": [
          "unlinkKnowledgeFromRecord"
        ],
        "parsers": [
          "parseKnowledgeRelationMutation"
        ],
        "procedures": [
          "sp_kc_UnlinkKnowledgeFromRecord"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "record-activity",
    "title": "Record activity",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.record-activity",
    "apiBasePaths": [
      "/api/modules/record-activity"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/record-activity/records",
        "browserFunctions": [
          "searchRecordActivity"
        ],
        "parsers": [
          "parseRecordActivitySearch"
        ],
        "procedures": [
          "sp_RecordActivity_SearchSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/record-activity/{recordId:guid}",
        "browserFunctions": [
          "getRecordActivity"
        ],
        "parsers": [
          "parseRecordActivity"
        ],
        "procedures": [
          "sp_RecordActivity_GetSecured",
          "sp_Calendar_GetSecured",
          "sp_Calendar_CreateSecured",
          "sp_Calendar_UpdateSecured",
          "sp_Developer_DeleteRecord",
          "sp_Calendar_SetFavoriteSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/record-activity/{recordId:guid}/favorite",
        "browserFunctions": [
          "setRecordActivityFavorite"
        ],
        "parsers": [
          "parseFavoriteMutation"
        ],
        "procedures": [
          "sp_Favorites_SetSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "global-search",
    "title": "Global secured search",
    "integrationKind": "page-module",
    "nativeComponentKey": "module.global-search",
    "apiBasePaths": [
      "/api/modules/global-search"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/global-search",
        "browserFunctions": [
          "searchGlobalRecords"
        ],
        "parsers": [
          "parseGlobalSearch",
          "parseSecuredRecordCount"
        ],
        "procedures": [
          "sp_GlobalSearch_SearchSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/global-search/count",
        "browserFunctions": [
          "searchGlobalRecords"
        ],
        "parsers": [
          "parseGlobalSearch",
          "parseSecuredRecordCount"
        ],
        "procedures": [
          "sp_GlobalSearch_CountSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/global-search/records/{recordId:guid}/favorite",
        "browserFunctions": [
          "setGlobalSearchFavorite"
        ],
        "parsers": [
          "parseFavoriteMutation"
        ],
        "procedures": [
          "sp_Favorites_SetSecured"
        ]
      }
    ],
    "integrationNote": "Use the current typed client or the exact operations listed here."
  },
  {
    "slug": "api-account-admin-api",
    "title": "Account Admin API",
    "integrationKind": "api-surface",
    "nativeComponentKey": "module.account-admin",
    "apiBasePaths": [
      "/api/account-admin"
    ],
    "clientMethods": [],
    "operations": [],
    "integrationNote": "This API surface supports other first-class modules and has no standalone page renderer."
  },
  {
    "slug": "api-inbox-support-lanes-api",
    "title": "Support Lanes API",
    "integrationKind": "api-surface",
    "nativeComponentKey": "module.support-lanes",
    "apiBasePaths": [
      "/api/inbox/support-lanes"
    ],
    "clientMethods": [],
    "operations": [],
    "integrationNote": "This API surface supports other first-class modules and has no standalone page renderer."
  },
  {
    "slug": "api-modules-company-iq-api",
    "title": "Company Iq API",
    "integrationKind": "api-surface",
    "nativeComponentKey": "module.company-iq",
    "apiBasePaths": [
      "/api/modules/company-iq"
    ],
    "clientMethods": [],
    "operations": [],
    "integrationNote": "This API surface supports other first-class modules and has no standalone page renderer."
  },
  {
    "slug": "api-modules-ops-atlas-api",
    "title": "Ops Atlas API",
    "integrationKind": "api-surface",
    "nativeComponentKey": "module.ops-atlas",
    "apiBasePaths": [
      "/api/modules/ops-atlas"
    ],
    "clientMethods": [],
    "operations": [],
    "integrationNote": "This API surface supports other first-class modules and has no standalone page renderer."
  },
  {
    "slug": "api-modules-payments-api",
    "title": "Payments Module API",
    "integrationKind": "api-surface",
    "nativeComponentKey": null,
    "apiBasePaths": [
      "/api/modules/payments"
    ],
    "clientMethods": [],
    "operations": [
      {
        "method": "GET",
        "route": "/api/modules/payments/settings",
        "browserFunctions": [
          "getTenantPaymentSettings"
        ],
        "parsers": [
          "parseTenantPaymentSettings"
        ],
        "procedures": [
          "sp_TenantPayments_GetSettingsSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/payments/settings/{moduleKey}",
        "browserFunctions": [
          "updateTenantPaymentPolicy"
        ],
        "parsers": [
          "parseTenantPaymentMutation"
        ],
        "procedures": [
          "sp_TenantPayments_UpdatePolicySecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/payments/connectors",
        "browserFunctions": [
          "upsertTenantPaymentConnector"
        ],
        "parsers": [
          "parseTenantPaymentMutation"
        ],
        "procedures": [
          "sp_TenantPayments_UpsertConnectorSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/payments/connectors/{connectorId:guid}",
        "browserFunctions": [
          "deactivateTenantPaymentConnector"
        ],
        "parsers": [
          "parseTenantPaymentMutation"
        ],
        "procedures": [
          "sp_TenantPayments_DeactivateConnectorSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/payments/methods",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_TenantPayments_ListMethodsSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/payments/methods",
        "browserFunctions": [
          "registerTenantPaymentMethod"
        ],
        "parsers": [
          "parseTenantPaymentMutation"
        ],
        "procedures": [
          "sp_TenantPayments_CreateMethodSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/payments/methods/{paymentMethodId:guid}",
        "browserFunctions": [
          "getTenantPaymentMethod"
        ],
        "parsers": [
          "parseTenantPaymentMethod"
        ],
        "procedures": [
          "sp_TenantPayments_GetMethodSecured"
        ]
      },
      {
        "method": "PUT",
        "route": "/api/modules/payments/methods/{paymentMethodId:guid}/default",
        "browserFunctions": [
          "setDefaultTenantPaymentMethod"
        ],
        "parsers": [
          "parseTenantPaymentMutation"
        ],
        "procedures": [
          "sp_TenantPayments_SetMethodDefaultSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/payments/methods/{paymentMethodId:guid}",
        "browserFunctions": [
          "revokeTenantPaymentMethod"
        ],
        "parsers": [
          "parseTenantPaymentMutation"
        ],
        "procedures": [
          "sp_TenantPayments_RevokeMethodSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/payments/records/{recordId:guid}",
        "browserFunctions": [
          "getTenantRecordPayments"
        ],
        "parsers": [
          "parseTenantRecordPaymentSummary"
        ],
        "procedures": [
          "sp_TenantPayments_GetRecordSummarySecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/payments/records/{recordId:guid}/charges",
        "browserFunctions": [
          "createTenantRecordCharge"
        ],
        "parsers": [
          "parseTenantPaymentMutation"
        ],
        "procedures": [
          "sp_TenantPayments_CreateChargeSecured"
        ]
      },
      {
        "method": "DELETE",
        "route": "/api/modules/payments/records/{recordId:guid}/charges/{chargeIntentId:guid}",
        "browserFunctions": [
          "cancelTenantRecordCharge"
        ],
        "parsers": [
          "parseTenantPaymentMutation"
        ],
        "procedures": [
          "sp_TenantPayments_CancelChargeSecured"
        ]
      },
      {
        "method": "GET",
        "route": "/api/modules/payments/attention",
        "browserFunctions": [],
        "parsers": [],
        "procedures": [
          "sp_TenantPayments_ListAttentionSecured"
        ]
      },
      {
        "method": "POST",
        "route": "/api/modules/payments/records/{recordId:guid}/charges/{chargeIntentId:guid}/attention",
        "browserFunctions": [
          "resolveTenantPaymentAttention"
        ],
        "parsers": [
          "parseTenantPaymentAttentionReceipt"
        ],
        "procedures": [
          "sp_TenantPayments_ResolveAttentionSecured"
        ]
      }
    ],
    "integrationNote": "This API surface supports other first-class modules and has no standalone page renderer."
  },
  {
    "slug": "api-runtime-record-types-api",
    "title": "Record Types API",
    "integrationKind": "api-surface",
    "nativeComponentKey": "module.record-types",
    "apiBasePaths": [
      "/api/runtime/record-types"
    ],
    "clientMethods": [],
    "operations": [],
    "integrationNote": "This API surface supports other first-class modules and has no standalone page renderer."
  }
] as const satisfies readonly HeadlessCapabilityRecipe[];
```

## 9. Headless release checklist

- Run a real login, refresh, reload, logout and expired-session journey; do not mock the transport in the only end-to-end test.
- Probe every detail and mutation with an own ID, another tenant's real ID, and a random ID. Foreign/absent responses must not become an existence oracle.
- Verify DataRole, Location, secure-field, AI-read and action permission changes take effect on the next request.
- Assert list cardinality, stable ordering, first/middle/deep pagination, bounded payload size and no client-side “fetch everything then filter” path.
- Exercise create/update/stale update/duplicate request, file failure, Workflow approval, ticket resolution, Inbox activity changes, rate limiting and restart recovery.
- Keep correlation IDs through browser, API, SQL, workers and provider delivery; log safe codes, never tokens, secrets, SQL parameters or returned tenant data.
- Test keyboard/screen-reader behavior, mobile layout, large photos, slow connections, 401/403/404/409/429/5xx states and abort/navigation races.

Use the [native React catalog](react-component-catalog.html)  when the platform component already matches the experience, and the [Developer Platform](../api/index.html)  for external/server-to-server applications.

Compare all six styling approaches in [Support for React](support-for-react.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/headless-application-kit.html).

---
title: "Monaco advanced JSON mode"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/raw-json-mode.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Monaco advanced JSON mode

Edit the canonical page document directly in Monaco with the same validation and publish fences.

## In brief

- **Audience:** Advanced builders
- **Risk:** Guard-railed
- **Related:** Page editor

Every page has one canonical JSON document. **Monaco (advanced)** edits that same document directly for builders who need precise structural control. **Puck remains the primary editor**; switching editors does not fork the page or create a second source of truth.

## What the validator protects

Every block carries a stable identity that the template upgrade system uses to merge changes safely. If a raw edit would **remove or duplicate a block identity**, the save is blocked with error `E021` until you explicitly acknowledge the loss. This isn't bureaucracy — losing those identities means future template upgrades can no longer match your customized blocks to their upstream versions.

Important

Acknowledging E021 is permanent for the affected blocks. They will be treated as brand-new content in every future template upgrade. If you're not sure, cancel and ask what the edit is removing.

## Returning to Puck

You can switch back to Puck only when the document parses and passes the editor's structural checks. A malformed edit cannot enter the visual editor, save as a valid draft, or reach the live page. The same edit lease, expected version, validation, and exact-draft publish rules apply in both editors.

## When to use it

- Bulk find-and-replace across a large page
- Pasting a block structure between pages
- Inspecting exactly what a block is configured to do

Page JSON describes presentation and approved bindings; it does not encode a user's authorization. DataRoles, Locations, field rules, and action checks are evaluated by runtime services for the signed-in person.

## Exporting the application definition

Builders can export the versioned JSON documents and JSON Schema contracts that define an application's pages and workflows. The package preserves the portable application definition - including component configuration, approved bindings, workflow steps, and version metadata - without exporting live credentials.

This is different from a customer data export. The application-definition package describes how the product behaves; an account data package contains only the authorized organization's records and related artifacts, while a whole-SaaS backup contains the app's databases and must remain restricted to authorized operators. Together with the continuity runtime, the two packages support migration or recovery outside BuildWithHQ. See [Business continuity and application portability](../trust/business-continuity-and-portability.html).

Tip

For everyday layout work, Puck is faster and safer. Reach for Monaco when you need surgical precision.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/raw-json-mode.html).

---
title: "Templates, forks, and upgrades"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/templates-forking.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Templates, forks, and upgrades

Start from a template, customize freely, and still receive upstream improvements.

## In brief

- **Audience:** Builders
- **Concept depth:** Core mental model
- **Related:** Page editor

Templates give you a finished starting point. The moment you customize a templated page, you've **forked** it — your copy is yours, and nothing upstream ever overwrites it without your say-so. But you don't lose the upstream relationship either.

## The three layers

1. **Base template** — the published version in the library. Immutable once released; new releases create new versions.
2. **Your fork** — your customized copy, with a record of the exact baseline you forked from.
3. **Bespoke pages** — premium custom engineering work, fully excluded from automated upgrades to protect the investment.

## Selective upgrades

When a template gets a new release, you'll see the changes block-by-block, side by side with your version. You choose which upstream blocks to pull in; everything you've customized and don't select stays exactly as it is. Behind the scenes the platform matches blocks by their stable identities and performs a three-way merge between the original baseline, the new release, and your fork.

Note

If a block was deleted on one side and edited on the other, the upgrade flags it for your decision instead of silently choosing — a destructive merge is never automatic.

## Practical guidance

- Customize freely — forking is the intended workflow, not a deviation.
- Review upgrade notices when they appear; small, frequent adoptions merge more cleanly than year-old jumps.
- Avoid deleting blocks you might want upgraded later; hide or empty them instead.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/templates-forking.html).

---
title: "Menus and User Types"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/menus-user-types.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Menus and User Types

Create a User Type, assemble its menu from shared or independent pages, and publish safely.

## In brief

- **Audience:** Builders
- **Build order:** User Type to published page
- **Primary editor:** Puck

The Design workspace follows one deliberate order: **User Types → menus → shared pages**. A User Type selects an audience's starting page, layout and menu. Its menu arranges navigation links; an entitled published page may also be opened directly. DataRoles and Locations remain separate and decide what data the signed-in person may use on each requested page.

## From User Type creation to publish

1. Inside the SaaS, open **Design**.
2. Under **User Types**, create or select the audience. Give a new type a stable key and a clear display name.
3. Choose its dashboard/home page.
4. Add pages to the menu with **Add existing**, **Duplicate**, or a new blank page.
5. Order the menu items, remove anything this audience does not need, and choose **Save menu**.
6. Select the page you want to edit. Build it in Puck, using Monaco only for advanced canonical JSON work.
7. Preview the presentation, save the draft, validate it, resolve every error and warning, then publish the exact validated draft.
8. Sign in as a representative user of that type and test navigation, direct routes, records, fields, locations, and permitted actions.

## Add existing or Duplicate?

| Choice | What it creates | Use it when |
| --- | --- | --- |
| **Add existing** | Adds the same PageKey to this menu. The page content is shared; publishing an edit updates every User Type that uses that page. | The audiences use the same workflow or layout, even if their authorized data differs. |
| **Duplicate** | Creates a new independent PageKey with copied starting content. Later edits and publishes are isolated. | An audience genuinely needs a different layout or workflow that should diverge. |
| **Blank page** | Creates a new independent PageKey and empty starting document. | No existing page is a useful starting point. |

Tip

Do not duplicate a page merely to change data access. Reuse the page and assign each person the correct DataRoles and Locations.

## Shared pages can appear in several menus

A single page may be a dashboard, appear in multiple User Type menus, or occupy a different menu position for each audience. Each menu can give the same existing page a different label without creating another page. The Shared pages list shows menu-placement and dashboard-usage counts so you can understand the impact before editing or publishing it.

## Direct-route behavior

User Types choose menus, layouts, and starting pages. An active, entitled published page can be opened directly even when it is absent from the current menu. Removing a menu link changes navigation; it does not revoke access to the page or its data.

The server resolves each request from the verified user, tenant organization, SaaS app, and persisted page identity. It selects the applicable tenant page, customization or fork, or base page from the database. A menu label is presentation text, never a guessed page name or permission.

Route eligibility is still not data authorization. Assigning a page does not grant a record, field, export, AI retrieval, location, or mutation. Those checks use the signed-in person's DataRoles, Locations, and action-specific permissions each time.

## Safe collaboration and publishing

Menu and page saves use version checks. If another editor publishes or changes the menu first, reload and review the current state instead of overwriting it. Unsaved menu changes prevent page publishing. Preview is non-interactive and User Type simulation changes presentation only; it never borrows another audience's data permissions.

See [Build and publish SaaS pages](page-editor.html)  for the Puck, Monaco, preview, validation, and revision workflow, and [Tenant Data Security](../trust/tenant-data-security.html)  for the three independent security dimensions.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/menus-user-types.html).

---
title: "Workflows"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/workflows.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Workflows

Automate multi-step processes on your data: branching, approvals, waits, and AI steps.

## In brief

- **Audience:** Builders
- **Skill level:** Intermediate
- **Runs:** In the background

Workflows carry out multi-step processes automatically — when a record is created, when a date passes, or when someone kicks one off by hand. Steps run in the background and every run keeps a complete history.

## Step types at a glance

| Step | What it does |
| --- | --- |
| Update / create records | Change data as part of the process |
| Conditional branch | Take different paths depending on field values |
| Wait | Pause for a duration or until a relative date |
| Require approval | Stop and hold until an authorized person signs off; the affected record locks for editing while it waits |
| AI action | Send content to the AI fleet for summarization or extraction, and use the result downstream |
| Notify | Send a notification to a user or role |

## Editing a live workflow

Editing a workflow never disturbs runs already in flight. Your edit becomes a new version; new runs use it, and existing runs finish safely on the definition they started with.

## Watching runs

Every run shows its step-by-step history — what ran, what it changed, and where it's waiting. Failed steps retry automatically before surfacing as failures you can inspect.

Tip

Start with one small workflow that saves ten minutes a day, confirm it behaves, then grow it. Big first workflows are where debugging time goes to live.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/workflows.html).

---
title: "Universal Inbox"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/universal-inbox.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Universal Inbox

External email, SMS, web forms, and other inbound communications in one attention layer—unsorted or routed, always actionable.

## In brief

- **Audience:** Builders
- **Default intake:** Unsorted / triage
- **Related:** GoClaw assistant

The Universal Inbox is the common attention layer for communication and work arriving from outside your organization. Configured email, SMS/text messages, web-form submissions, and other authenticated inbound sources all become visible in one place—whether they are still unsorted or have already been classified and routed.

## Every inbound source keeps its real record

- **Email and SMS** normalize into native Conversations and messages, then create or update Inbox attention.
- **Web forms** remain native form submissions and create or touch the Inbox item that needs review.
- **Other inbound endpoints** retain their canonical source record and project only the attention/ownership state into Inbox.

The Inbox does not replace Conversations, forms, customers, cases, or other business records. It points to them so a user can triage and act with the full authorized source context.

## Turn an email address into a support-ticket channel

A tenant account owner can open **Email ticketing setup** in Universal Inbox and enable the **Ticketing** checkbox for an individual inbound email address. Choose a short prefix such as `SUP`. Each new conversation received by that mailbox then receives one permanent, mailbox-scoped number such as `SUP-000123`.

Replies on the same conversation retain the ticket number. Turning Ticketing off stops numbering new conversations but does not erase existing ticket identities. Other email addresses continue to behave as normal Inbox channels.

## Ticket resolution states

Support tickets deliberately reuse the Inbox lifecycle: **New**, **Open**, **WaitingCustomer**, **WaitingInternal**, **Snoozed**, **Resolved**, and **Closed**. The Support tickets view filters to numbered items, and the ticket detail labels this shared state as its resolution state. A new inbound reply reopens resolved or closed work through the normal Inbox activity path and increments `ActivityVersion`.

## Unsorted first, routed when ready

If an item does not match a routing rule, it stays visible in an **Unsorted** or **Triage** queue. Nothing should disappear because the system could not classify it. Rules—and permitted AI classification—can then set queue, owner, priority, tags, due/SLA attention, and next workflow.

Common routing destinations include:

- **Personal** — conversations belong to one person (a rep's own line).
- **Role-routed** — conversations go to everyone holding a role (e.g., Support).
- **Shared** — conversations are visible to the whole workspace.

## Sort and act

From an Inbox item, an authorized user can open the native source, assign or reassign ownership, change queue/priority, add tags, snooze, reply, create follow-up work, link records, start a workflow, approve a GoClaw suggestion, or complete the item. The exact actions depend on the source record and the user's existing action permissions.

## Permission and stale-context protection

Routing never grants access. The signed-in user must still be allowed to read the source record under the tenant, DataRole, field, and location rules. New source activity increments the Inbox `ActivityVersion`; a reply or action prepared against an older version must be reviewed again rather than executing stale work.

Tip

Treat the Unsorted/Triage queue as an operational safety net. Give it an owner and SLA, then improve routing rules from the real items that land there.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/universal-inbox.html).

---
title: "The AI assistant"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/ai-assistant.html"
reviewed_at: "2026-09-14"
authority: Official
---

# The AI assistant

A per-user assistant that drafts, triages, and acts — always inside an approval queue you control.

## In brief

- **Audience:** Builders
- **Control model:** Approve-before-act
- **Related:** Universal Inbox

Each enabled user account can have a dedicated GoClaw assistant that watches work routed to that user and prepares it: researching permitted context, classifying, drafting replies, extracting details, and suggesting next steps.

## The same permission layer as the user

GoClaw acts on behalf of its user; it is not a privileged service account. Every read is limited by that user's tenant, DataRole, record, field, and location permissions. AI-specific `CanAiReadRecords`, secure-field exclusions, tool policy, and quotas can narrow access further, but the assistant can never widen it.

## The approval queue

Customer-facing or material actions land in the approval queue unless an explicit reviewed policy permits that exact low-risk action. Users can review evidence and inputs, edit where allowed, and approve or dismiss. Planning and research alone never mutate business state.

## Daily limits

Each assistant has a daily action budget, enforced by the platform itself. When it's reached, further actions queue for the next day. If users report the assistant "stopped working" late in the day, check the quota first — it's the most common cause.

## Attribution

Every artifact the assistant produces is tagged with what created it and from which conversation, so there's never ambiguity about whether a person or an assistant wrote something.

Note

The assistant's effective access is never larger than the user's and may be smaller because AI-specific read, tool, quota, approval, and stale-context gates also apply.

For the complete control model — every layer that keeps the assistant useful without ever being able to run away with it — see [GoClaw in depth](goclaw-in-depth.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/ai-assistant.html).

---
title: "GoClaw in depth: acting on a user's behalf, under control"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/goclaw-in-depth.html"
reviewed_at: "2026-09-14"
authority: Official
---

# GoClaw in depth: acting on a user's behalf, under control

The complete control stack that lets the assistant do real work without ever being able to run away with it.

## In brief

- **Design stance:** Layered, structural limits — not promises
- **Audience:** Builders enabling assistants
- **Related:** The AI assistant, AI insights

GoClaw is the platform's per-user assistant: it watches the conversations routed to a user, prepares replies and next steps, and — with approval — carries them out. The question every builder should ask before enabling it is the right one: *what stops it from getting out of control?* The answer is a stack of independent limits, each enforced by the platform rather than by the assistant's good behavior. For GoClaw to misbehave, every layer would have to fail at once.

## Layer 1 — It sees only what its user sees

GoClaw is bound to one user account and has no wider identity in tenant data. Every read is constrained by that user's tenant, DataRole, record, field, and location permissions. A user scoped to one location gets an assistant scoped to one location. AI-specific `CanAiReadRecords`, tool policy, and quota checks can narrow the assistant further; nothing about being an assistant widens access by a single record. Fields marked secure are [structurally invisible](secure-fields.html)  because encrypted values never enter search or AI context.

## Layer 2 — It only works channels you've handed it

The Universal Inbox can receive all configured outside email, SMS, web-form, and other inbound communication, including items still waiting in Unsorted/Triage. GoClaw does not roam all of it: it engages only on items and queues routed to its user and explicitly enabled for assistant preparation. Shared and role-routed work stays human unless policy and assignment deliberately bring it into that user's scope.

## Layer 3 — It proposes; a person disposes

Every action GoClaw wants to take — send this reply, create this task, update this record — lands in its user's approval queue first. The user edits, approves, or dismisses. An unapproved proposal does nothing, forever. This is the default and there is no “fully autonomous” switch to flip by accident.

## Layer 4 — A hard daily budget, enforced by the platform

Each assistant has a maximum number of actions per day, checked **server-side at the moment an action is queued** — not in the assistant's own logic, where a bug could ignore it. At the limit, the platform refuses further actions with error `51005` and they wait for the daily reset. Even a hypothetically misbehaving assistant is mechanically rate-capped.

## Layer 5 — Everything it makes is labeled

Every artifact GoClaw produces — drafts, records, tasks — is tagged with what created it and which conversation it came from. There is never ambiguity about whether a person or an assistant did something, which matters the day a customer asks.

## Layer 6 — Behavior is tested before it ships

The behavior configuration an assistant runs can be gated through [Harness Packs](harness-packs.html)  — scored scenario suites a configuration must pass before promotion. Quality is a gate, not a hope.

## Layer 7 — Its work is graded, and the grades go somewhere

Every executed action can be rated, every suggestion records how users responded to it, and the assistant's reasoning is stored for inspection. Poor results are diagnosable and fixable, with Harness Packs gating each fix before it ships. See [Rating GoClaw and improving results](goclaw-ratings.html).

## What this means in practice

| Worry | Why it can't happen |
| --- | --- |
| “It'll read data it shouldn't” | It has no access of its own — it reads as its user, minus secure fields. |
| “It'll send something embarrassing” | Nothing sends without a human approving that specific message. |
| “It'll go haywire and spam actions” | The daily quota is enforced by the platform, outside the assistant. |
| “We won't know what it did” | Full attribution on every artifact, plus the standard audit trail. |
| “It'll wander into channels we didn't intend” | It only operates on lines explicitly marked assistant-managed. |

Note

Rolling out well: start with one or two users, a conservative daily quota, and only their personal lines. Widen after a week of reviewing what actually lands in the approval queues — the queue history is your evidence.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/goclaw-in-depth.html).

---
title: "Rating GoClaw and improving results"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/goclaw-ratings.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Rating GoClaw and improving results

Every action can be rated, every suggestion explains itself — so poor results can be diagnosed, not just endured.

## In brief

- **Explicit signal:** 1–5 rating + comment on any executed action
- **Implicit signal:** Every suggestion's fate is recorded
- **Diagnosis:** The AI's reasoning is stored, not discarded

An assistant you can't grade is an assistant you can't improve. GoClaw is built the other way around: every piece of work it does generates signals, every suggestion keeps a record of *why* it was made, and the path from “that was a bad draft” to “here's exactly what to change” is a read, not a guess.

## The signals, explicit and implicit

**Explicit ratings.** After an action executes, the user can rate it one to five, mark whether it was helpful, and leave a comment. Ratings attach to the specific execution — not to the assistant in general — so a 2-star is always a 2-star *on something inspectable*.

**Implicit responses.** Richer still: every suggestion the assistant makes records its fate — accepted, dismissed, ignored, or *modified and accepted* — along with where it ranked in the list and how confident the AI was at the time. Nobody has to remember to rate anything for this signal to accumulate; using the assistant normally produces it.

**Rejection reasons.** When an approver rejects a queued action they can say why, and the reason is stored on the action and in its event trail. A week of rejection reasons is a tuning brief written by your own users.

| Response | What it tells you |
| --- | --- |
| Accepted as-is | The draft was right. The baseline you're protecting. |
| Modified, then accepted | The most valuable signal there is: the *idea* was right, the *execution* needed polish. Read the edits — they're your users showing you the target. |
| Dismissed | Wrong action for the moment. If one action type is dismissed persistently, its triggering conditions are too broad. |
| Ignored | Not even engaged with. Chronic ignoring means suggestions are surfacing at the wrong time or place, not just with the wrong content. |

## Diagnosing a poor rating

What makes diagnosis possible is that the assistant's homework is retained. Each suggestion stores a **snapshot of the data it saw** at that moment and its **reasoning** — the factors it weighed, how heavily, and the alternative actions it considered with their scores. Each execution stores a **step-by-step trail**: every step's input, output, duration, and any error. So a bad outcome decomposes into one of three findings:

| Finding | You'll see it in | The fix lives in |
| --- | --- | --- |
| **It saw the wrong data** — the snapshot is missing or stale relative to reality | The context snapshot vs. the actual record at that time | Data quality and what context the action is fed — not the AI's behavior |
| **It reasoned poorly** — right data, wrong weighting or wrong alternative chosen | The reasoning's factors and the scores on alternatives it passed over | The behavior configuration: prompts, factor emphasis, and the conditions that trigger each action type |
| **It executed badly** — right decision, a step failed or produced a poor artifact | The execution steps: which one erred, how long it took, what it emitted | The specific step — a template, a connected channel, a timeout |

Tip

Start every diagnosis with the reasoning, not the output. “What did it think it was doing, and was that reasonable given what it saw?” separates a data problem from a judgment problem in about thirty seconds — and they have completely different fixes.

## Closing the loop

Diagnosis without a safe way to ship the fix just moves the frustration. The improvement loop here is deliberately gated:

1. **Read the signals** — ratings, response patterns, and rejection reasons, sliced by action type. One action type usually accounts for most of the pain.
2. **Diagnose with the stored evidence** — snapshot, reasoning, steps, as above.
3. **Adjust the behavior configuration** — the prompt, the triggering conditions, the context provided, or simply disabling an action type that isn't earning its place.
4. **Prove it before it ships** — run the candidate configuration through a [Harness Pack](harness-packs.html)  that includes scenarios built from the failures you just diagnosed. A fix that passes the scenarios that used to fail is a fix; anything else is a hope.
5. **Promote and watch the same metrics** — the ratings and response rates that flagged the problem are the same ones that confirm the cure.

Note

Feedback also works passively: user responses feed suggestion ranking over time, so consistently dismissed suggestions sink and consistently accepted ones surface earlier — the feed self-corrects between your deliberate tuning passes.

## The numbers worth watching

- **Acceptance rate by action type** — the headline. A type below your comfort line is a tuning candidate; a type near zero should be switched off until fixed.
- **Modified-and-accepted share** — high is actually encouraging early on (right ideas, improvable drafts); the goal is converting it into accepted-as-is by learning from the edits.
- **Rating trend across a configuration change** — the before/after that tells you whether a tuning pass worked in production, not just in the Harness Pack.
- **Ignore rate** — the placement-and-timing metric. Content fixes won't move it; where and when suggestions appear will.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/goclaw-ratings.html).

---
title: "Build with AI"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/build-with-ai.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build with AI

Describe the product you want in a guided interview and get a drafted, working application.

## In brief

- **Audience:** Builders
- **Time:** 20–30 min
- **Output:** A working draft app

Instead of assembling an application by hand, you can describe it. The Build-with-AI interview asks structured questions about your product — who uses it, what it tracks, what should happen automatically — and drafts the application from your answers.

## How the interview works

The interview is conversational but produces a precise blueprint: pages, data structures, user types, and menus. You review the blueprint before anything is created — it's a plan you approve, not a surprise.

## From blueprint to app

On approval, the platform materializes the blueprint into a real application, seeded from the template library where good starting points exist. From there it's a normal app: every page is editable, every menu adjustable, nothing locked.

Tip

Be concrete in the interview. “Track service jobs with a scheduled date, an assigned tech, and a completion checklist” drafts far better than “a field service app.”

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/build-with-ai.html).

---
title: "Secure fields"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/secure-fields.html"
reviewed_at: "2026-10-22"
authority: Official
---

# Secure fields

Per-field encryption for your most sensitive data — and what it deliberately turns off.

## In brief

- **Audience:** Builders
- **Security level:** Field-level encryption
- **Trade-off:** No search on encrypted fields

Supported Contact secure fields provide encrypted storage, masked display and an explicit permission-checked reveal. Availability depends on the module, field definition and configured key protection. Do not assume that every field or module has a working reveal flow. Confirm the enabled controls in your app before storing sensitive values.

## What changes when a field is secure

- Values are stored encrypted; they never sit readable in the database.
- Reading requires an explicit **reveal** action by an authorized user — values don't display in lists by default.
- **The field drops out of search and AI features entirely.** Encrypted values are invisible to search indexing and to AI assistants — structurally, not as a setting someone could misconfigure.

Important

The search trade-off is the point, not a limitation to work around. If a field must be searchable, it cannot be a secure field — decide which property matters more for each field before enabling.

## What to secure

Good candidates: government ID numbers, bank details, health notes, credential-like values. Poor candidates: names and emails you need to search by, fields that drive workflow branching.

---

Capability review: 2026-10-22. [View the canonical guide](https://support.buildwithhq.com/builder-guide/secure-fields.html).

---
title: "Marketplace and add-ons"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/marketplace.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Marketplace and add-ons

Install extensions into your apps — from single components to complete bundles.

## In brief

- **Audience:** Builders
- **Time:** Varies by add-on
- **Billing:** Per add-on

The marketplace offers add-ons that extend your applications: components, template packs, and container-based services that run alongside your app. Products install as single items or as bundles whose components install in a defined order.

## Installing

Pick a product, review what it includes and what it costs, and install into a chosen app. Bundles show each included component and whether it's required or optional.

## Container-based add-ons

Some add-ons run as isolated services with their own compute. These are held to a strict disclosure standard: every access they make to your tenant data is written to a tamper-evident ledger your customers can verify. What an add-on runs is frozen and fingerprinted at the moment it's invoked, so the audit trail reflects exactly the code that touched the data.

Note

Add-ons never get blanket access to your data. Their network reach is sealed or allow-listed, and their data access is logged in a ledger that cannot be silently edited after the fact.

For the full model — declared endpoints, egress policies, immutable versions, and fingerprints — see [Appliances and their endpoints](appliances-and-endpoints.html). And if you've built something worth selling yourself, the [Selling Templates](../selling/index.html)  section covers the other side of the counter.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/marketplace.html).

---
title: "Appliances and their endpoints"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/appliances-and-endpoints.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Appliances and their endpoints

How container appliances declare what they do, what they can reach, and why none of it can change after release.

## In brief

- **Audience:** Builders installing or publishing appliances
- **Core idea:** The manifest is a contract, frozen at release
- **Related:** Marketplace, Audit & disclosure

An appliance is a container-based add-on that runs alongside your application with its own compute — typically for heavier processing your app calls out to. What makes appliances safe to install is that everything an appliance can do is **declared up front in a manifest, verified at publish, and frozen for the life of that version**. Nothing is discovered at runtime; nothing can quietly change.

## Endpoints: the appliance's entire surface

An appliance can only be called at the endpoints its manifest declares. Each endpoint is a complete contract:

| Declared per endpoint | What it controls |
| --- | --- |
| **Key and route** | A stable name and the HTTP method + path it answers on. Your app's actions bind to the key, so a new version can keep its promises even if internals change. |
| **Input and output schemas** | The exact shape of what goes in and what comes back. Calls that don't match the input schema are rejected before the appliance sees them. |
| **Required permission** | The platform permission a caller must hold. An endpoint with a required permission simply cannot be reached by a user who lacks it. |
| **Timeout and execution mode** | How long a call may run (default 60 seconds) and whether it answers synchronously or hands back a job to poll. |

A version with no declared endpoints cannot be published at all — an appliance with nothing callable is a packaging error, and the platform treats it as one.

## Egress: sealed or allow-listed, never open

Network reach out of an appliance follows one of exactly two policies, chosen at release:

- **Sealed** — the appliance can reach nothing outside the platform. Most appliances should be sealed; if the manifest declares any outside destination, publishing as sealed is refused.
- **Allow-listed** — the appliance may reach only the destinations its manifest names, each as a specific host and port with a stated purpose. Declaring the allow-list policy with an empty list is likewise refused — the two must agree.

When you review an appliance before installing, its egress list *is* its network behavior. An empty list means sealed. There is no third state.

## Versions are immutable, and provably so

Every release carries a **fingerprint** computed from the manifest, the exact container image digest, and the egress policy together. The image digest must be stated inside the manifest itself and match the image being released — a mismatch blocks the release. The result: the fingerprint identifies precisely one combination of code, contract, and network policy.

Versions move through a one-way lifecycle: **Draft → Published → Deprecated**. Only drafts can be edited; only published versions can be installed; deprecation sets a support-end date and removes the version from recommendation, without breaking existing installs. Releases can carry a publisher signature and a software bill of materials reference, and an emergency revocation path exists for a version that must be pulled.

## Every data access is on the record

When an installed appliance touches tenant data, the access is written to the tamper-evident disclosure ledger, with the version's code identity — that fingerprint — recorded at the moment of invocation. The audit trail therefore says not just *that* data was accessed but exactly *which code* accessed it. See [Audit trail and data disclosure](../trust/audit-and-disclosure.html).

Note

Reading an appliance listing, the questions to ask are always the same three: What endpoints does it expose? What can it reach (sealed, or which hosts)? What resources does it need? All three are in the manifest, and all three are frozen.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/appliances-and-endpoints.html).

---
title: "Connecting to external services"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/external-api-connections.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Connecting to external services

The four ways your app talks to the outside world, and how outbound credentials are kept safe.

## In brief

- **Directions:** Two in, two out
- **Credential rule:** Encrypted at rest, never shown again
- **Related:** Appliances, Webhooks

“API” covers four different things on this platform, and support confusion usually starts with mixing them up. Here is the whole map:

| Concept | Direction | What it is |
| --- | --- | --- |
| **API clients** | Inbound → your app | Keys you issue so outside software can call *your* application's API, limited to the scopes you grant. |
| **API connections** | Your app → outbound | Credentials you store so the platform can call *remote services on your behalf* — a CRM, a payment provider, a data source. |
| **Container services** | Alongside | Appliance endpoints, plus whatever egress their manifest allows. See [Appliances and their endpoints](appliances-and-endpoints.html). |
| **Webhook actions** | Your app → outbound | Workflow steps that push signed event payloads to URLs you register. |

## Outbound: API connections

To connect a remote service, you create a connection for the app and supply its credentials — an API key, a token, whatever the service issues. From then on, workflows and features reference the connection by name; nothing else in the platform ever handles the raw credential.

How the credential is treated:

- **Encrypted before storage** with AES-256-GCM in the application tier — the database only ever holds ciphertext.
- **Never returned** — not to the browser, not through any API. After you save it, the platform can use it; no one can read it back. Lost the value? Rotate it at the remote service and save the new one.
- **Decrypted only at the moment of an outbound call**, server-side.

Tip

Create credentials at the remote service with the narrowest permissions the integration needs. If the connection is only reading contacts, the key shouldn't be able to delete them — least privilege at their end is your best protection at ours.

## Inbound: API clients

Issuing access to your app works in the opposite direction with the same discipline. You create a client with a name and a set of scopes; the secret is shown **exactly once**, at creation, and only a hash is stored. Rotation issues a fresh secret (shown once again); revocation kills the client immediately. Managing clients requires the API-keys permission on your team role.

## Outbound: webhook actions

Workflow webhook steps sign every payload, so the receiving system can verify each delivery came from your app and wasn't altered. Build receivers idempotent — deliveries retry on failure and can occasionally repeat.

## Choosing the right mechanism

- Another system needs to *push data in or query your app* → issue an **API client**.
- Your app needs to *act on a remote service* → store an **API connection** and use it from workflows.
- Another system just needs to *know when things happen* → point a **webhook** at it.
- The work needs *real compute next to your data* → install an **appliance**.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/external-api-connections.html).

---
title: "Your container and Postgres database"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/container-and-postgres.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Your container and Postgres database

Extend an app with custom services and a separate Postgres store when the required compute environment is provisioned.

## In brief

- **Requires:** Provisioned service compute
- **Code:** Approved runtime and declared endpoints
- **Storage:** Separate service Postgres

Custom services extend an app with code and a separate Postgres store. The service environment must be provisioned and healthy before these instructions can be used. Creating a SaaS app or downloading the Developer Kit does not by itself prove that a service VM is running.

Note

Firecracker and GPU infrastructure are not yet online in the current launch environment. Treat this page as the service deployment model until the operator confirms compute readiness. Service Postgres is separate from the SaaS core, AI, and logs databases and does not grant direct access to their data.

## The container: your code, your rules

The container is a real compute environment attached to your application. Inside it, you're the developer, not the platform's guest:

- **Any stack.** Run whatever you can run in a container — Node, Python, Go,.NET, a compiled binary, a niche library the visual tools will never wrap.
- **Your own endpoints.** Expose HTTP endpoints on the container's port and they become part of your product's capability — custom calculations, integrations with systems nobody has a connector for, processing pipelines, whatever your vertical demands.
- **Configured, not improvised.** Environment variables carry your configuration; CPU and memory limits are declared per container; and the container's lifecycle — pending, running, stopped, failed — is tracked and visible, with deployments logged like everything else on the platform.

## The Postgres database: schema freedom

Alongside the platform's managed data engine, your application gets a Postgres database of its own. It exists for the data that doesn't want to live in a configurable record system: a bespoke relational schema, high-volume ingest from a device fleet, a data structure with twenty years of ecosystem tooling behind it. It's real Postgres — the full ecosystem applies — and its schema is whatever you say it is.

Two connection modes cover both directions of ambition: **managed**, where the platform hands your container its scoped connections, and **external**, where your container talks to databases you operate elsewhere. Start managed; the external mode means even “we already have infrastructure” isn't a wall.

## Wiring your code into the product

Custom code that can't reach the product is a science project. Yours can be wired in at every layer:

| From | How it reaches your code |
| --- | --- |
| **Pages** | Data-bound blocks can resolve through a Postgres connector, so a canvas component can display data your custom schema holds — under the same key-based binding model as everything else. |
| **Workflows** | Workflow steps call your endpoints, making your custom logic a first-class participant in automations. |
| **Your app's API** | Your container calls back into the application the same way any integration does — as an [API client](external-api-connections.html)  you issue, with scopes you choose. |

## The boundaries that still hold

Freedom inside the container doesn't dissolve the platform's rules around it:

- **Platform data access still goes through the platform.** Your code reading application records does so through the API, as an authenticated client — which means the permission model, the access logging, and every guarantee in the [security architecture](../trust/security-architecture.html)  apply to your code exactly as they apply to anyone else's. The container extends the product; it doesn't tunnel under it.
- **Resources are bounded.** Declared CPU and memory limits mean an experiment gone wrong in your container is your container's problem, not your users' outage.
- **Everything is logged.** Container deployments and lifecycle events land in the application's history like every other operational event.

## Contained means contained

Freedom inside the container is matched by hard walls around it — and the walls are worth understanding, because they're what makes it safe to hand every builder real compute in the first place.

**No escape upward.** The container is a genuine isolation boundary, not a chroot with ambitions. Your code has no path to the host, to the platform's runtime, or to other builders' containers. Whatever runs inside — including a dependency you didn't vet as closely as you meant to — stays inside.

**No sight sideways.** The container is not dropped onto the platform's network to be fenced in by firewall rules. Instead, it joins a private **overlay network** — the identity-based, WireGuard-encrypted model Tailscale popularized — where the container has its own cryptographic identity and an explicit access list defines the *only* internal services it can reach: its own Postgres database, its application's API, and nothing else. Everything else in the system isn't blocked from the container's point of view; it's *invisible*. There is no address to scan, no port to probe, no neighboring service to discover, because reachability is granted by identity, not implied by being on a network.

The practical consequence is what security reviewers actually ask about: a fully compromised container is a dead end. It can talk to its own database and make authenticated, permission-checked, logged API calls as the client you issued it — the same two things your legitimate code can do — and nothing more. Lateral movement requires a network to move laterally through, and from inside the container, that network doesn't exist.

Note

This is the same discipline applied twice: appliances get their outbound reach frozen in a manifest; your container gets its inbound view of the platform bounded by the overlay's access list. Different trust postures, same principle — nothing reachable by default, everything reachable on purpose.

## Container vs. appliance: which one is this?

The platform has two container stories, and they're opposites on purpose:

|  | Your container (this page) | [Marketplace appliances](appliances-and-endpoints.html)  |
| --- | --- | --- |
| **Whose code** | Yours — you wrote it, you trust it | A third party's — you're installing a product |
| **Freedom model** | Open: any stack, your endpoints, your schema | Sealed: endpoints and network reach frozen in a manifest at release |
| **Accountability** | You audit your own code | The platform audits it for you — fingerprints, egress logs, disclosure ledger |

Same substrate, opposite trust postures: maximum freedom for code you wrote, maximum verification for code you didn't. If you productize what you build here, the [selling pipeline](../selling/index.html)  is how it graduates into the second column for everyone else.

Note

This included container is distinct from the dedicated container-only runtime topology, which remains a premium option for regulated workloads needing physical isolation of the entire application runtime. Every app gets the extension container described here; the dedicated topology is a deployment choice on top.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/container-and-postgres.html).

---
title: "Snowflake analytics sync (tenant-operated)"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/snowflake-analytics-sync.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Snowflake analytics sync (tenant-operated)

Export selected organization log metadata to your own Snowflake account after connection verification and explicit enablement.

## In brief

- **Owner:** The tenant organization's active owner
- **Data:** Selected organization log metadata
- **Schedule:** Requires an available worker and separate enablement

Snowflake export copies selected log metadata from a tenant organization into a Snowflake account it controls. It is an analytics destination, not a complete backup of the application's records, files or logging history. See [Connect organization logs to Snowflake](../api/tenant-snowflake.html)  for the current datasets, setup steps and supported API routes.

## Who manages the connection?

The organization's active owner manages the destination in **Admin → Snowflake**. Builder support can use a Builder-managed live API credential only with explicit Snowflake scopes and a binding to that organization's active owner. A delegated tenant-user credential may use the same routes. The server verifies the app, organization and principal; entering an organization ID does not grant access.

## Verify and enable export

1. Save the destination and have a Snowflake administrator review and apply its setup SQL in the intended account. Saving a destination does not start export.
2. Run **Test connection** and require a successful connection result. HTTP 200 alone does not prove that Snowflake accepted the operation.
3. Explicitly enable the verified destination. Use **Export next batch** for a manual run.
4. For automatic export, first confirm that the scheduled host is available, then choose a cadence and explicitly enable the schedule. Enabling the destination does not enable its schedule.

Scheduling requires a configured worker with a recent heartbeat. When it is unavailable, the API reports `schedulingAvailable: false` and rejects new schedule-enable requests. Each run handles a bounded batch; one completed run does not mean the destination has caught up with all eligible source rows.

## Check delivery and recover failures

Review recent export history for each dataset's safe result, row count and correlation reference. Delivery checkpoints advance from Snowflake's confirmed offsets. An empty dataset may complete with zero rows. On a timeout or failure, refresh the status and follow the recovery guidance; do not reset or recreate a pipe or channel while a checkpoint exists without a reviewed recovery plan.

Prior integration checks exercised manual and scheduled export against an approved account. Those checks do not guarantee that a worker is running now or that every future batch will succeed. The current availability, destination verification and operation result remain the checks to use.

## What the copy contains

The export covers selected AI usage, login, page-view, record-change, field-access/change, file-access and automation-job metadata. It excludes passwords, session tokens, prompts, responses, record/file contents and raw diagnostic payloads. The [setup guide](../api/tenant-snowflake.html)  lists the eight datasets and their exact exclusions.

The tenant controls Snowflake access and retention after delivery. Export does not extend source-log retention, replace backups or transfer source integrity guarantees to the analytics copy. Consult the [tenant logging guide](../trust/tenant-logging.html)  for source-log integrity checks.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/snowflake-analytics-sync.html).

---
title: "Build with ActiveWorkplace"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/active-workplace.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build with ActiveWorkplace

Add and configure the recursive work module without creating a second record or permission system.

## In brief

- **Runtime key:** module.active-workplace
- **Data model:** Existing Records + coordination state
- **Authorization:** Existing tenant permissions

ActiveWorkplace gives an app a shared work surface around any permitted Record. The pinned Record and everything connected to it remain in their existing modules; the workplace adds coordination, responsibility, Pulse, attention, and history.

[Module reference](../first-class-modules/active-workplace.html) [User guide](../end-user/active-workplace.html) [Record Relations](../first-class-modules/record-relations.html) [Universal Inbox](universal-inbox.html)

## Add the block

1. Open the app and page in the Developer Console page editor.
2. Add `module.active-workplace` from First Class Modules.
3. Place the page in the existing menus for the User Types that should see it.
4. Configure bounded defaults, preview as representative users, and publish the normal exact app version.

## Configuration

| Setting | Safe starting point | Effect |
| --- | --- | --- |
| Allowed root module keys | Empty, or a short intended list | Filters which visible Record types the pin picker offers. It is product behavior, not authorization. |
| Maximum depth | 2 | How many relation hops a snapshot follows; supported range is 1–5. |
| Maximum nodes | 100 | Hard graph bound; supported range is 2–200. |
| Stale after | 3 days | Minutes without meaningful activity before Stale. |
| Warning before stale | 12 hours | How early the workplace becomes At Risk. |
| Participant types | User, GoClaw, Workflow | Which eligible participant pickers the block shows. |
| Default GoClaws | None initially | Eligible agents automatically added as non-acting watchers; server AI-read checks still apply. |
| Comments | Enabled | Shows the meaningful workplace update form. |
| Playback | Enabled | Allows retained historical inspection in read-only mode. |

Note

Block settings are never an authorization token. The browser can request a root, scope, or participant, but reviewed stored procedures re-derive the tenant/app/user envelope and refuse anything outside it.

## Design the Record graph first

Use a small vocabulary of meaningful typed relationships. ActiveWorkplace traverses existing `RecordRelations`; it does not infer a private parallel graph. Cycles are supported, but broad, vague relations can make a workplace noisy even when the hard bounds protect performance.

## Choose Pulse rules by work type

A support case may become stale after hours, while a contract review or opportunity may need days. Waiting suspends normal progress expectations until its date/reason is satisfied; Dormant is deliberate inactivity; Resolved closes the coordinated work. A deterministic worker evaluates timing and related Record updates without sending business data to a model.

## GoClaw and workflow defaults

Default assignment is a convenience only. The selected GoClaw must be active and its backing user must independently have `CanAiReadRecords` for the root. Keep material actions under human approval until their action-specific policy is proven. Published workflows remain limited to their existing definitions and permissions.

Tip

A good first launch uses people plus one read-only GoClaw watcher. Add deterministic actions only after the team trusts the Pulse and activity evidence.

## Acceptance test

- Pin one permitted root and confirm retry opens the same active workplace.
- Create a cycle and confirm the graph remains bounded.
- Relate a Record from another location and confirm it and its edges are absent.
- Try an AI-read-denied GoClaw and confirm assignment is refused.
- Advance Waiting into At Risk/Stale and confirm one Inbox item is touched on retry.
- Open playback, change the tester’s current location permission, and confirm the retained Record disappears or playback is denied.
- Confirm playback contains no write, workflow, GoClaw, participant, status, comment, refresh, or destructive controls.

Important

Do not place a customer secret, bearer token, database name, connection string, or copied business payload in workplace configuration. ActiveWorkplace needs Record identities and normal platform references only.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/active-workplace.html).

---
title: "Harness Packs"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/harness-packs.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Harness Packs

Test AI behavior configurations against scored scenarios before they touch real customers.

## In brief

- **Audience:** Builders using AI features
- **Purpose:** Pre-release AI quality gate
- **Related:** AI assistant

Before an AI behavior configuration serves your customers, you can run it through a Harness Pack: a set of scenarios with expected outcomes, scored automatically. Configurations that don't clear the bar don't ship.

## Why this exists

AI behavior is configuration, and configuration drifts. Harness Packs make quality a gate instead of a hope — the same way you wouldn't deploy code without tests.

## Working with packs

1. Choose or author a pack of scenarios relevant to your use case.
2. Run your candidate configuration against it; each scenario is scored.
3. Review failures, adjust, re-run. Promote only when the pack passes.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/harness-packs.html).

---
title: "Upgrade DB: staged database inventory"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/staged-database-upgrades.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Upgrade DB: staged database inventory

Review missing database dependencies before preparing a controlled SaaS upgrade.

## In brief

- **Location:** SaaS app → Backups
- **Access:** Authorized builder
- **Inventory:** Metadata, not customer records

Open your SaaS app's **Backups** page and find **Upgrade DB — Staged database inventory**. The panel displays the latest operator-published assessment of the Core, Logs, and AI databases.

## What the assessment checks

The scan compares database structure with the reviewed golden contracts: tables, column definitions and data types, SQL types, functions, views, stored procedures, dependencies, and permissions. It does not copy or display customer record values.

## Stage 1: missing procedures

- **Ready:** the procedure passes the dependency checks and can proceed to a restored-copy rehearsal.
- **Blocked:** required objects, columns, types, roles, or table contracts are missing or incompatible.
- **Manual review:** dynamic SQL, external references, triggers, unresolved dependencies, or other conditions need an operator's review.

Expand **Review missing procedures** to see names and reasons. Ready does not mean installed or approved. Existing procedures are not overwritten by the missing-procedure plan.

## Stage 2: missing schema and older modules

Stage 2 counts identify work needed before the remaining procedures can be installed: missing tables, columns, SQL types, functions/views, and reviewed updates to older modules. Operators must prepare migration-owned changes, including any required backfill or reference data. An inventory cannot safely decide those data transformations on its own.

## Refresh and approval are different actions

**Refresh inventory status** reloads the latest published assessment; it does not run a scan or change a database. If no inventory appears, ask the operator to run and publish the read-only scan. Scan time and fingerprint identify the assessment; the worker must recheck current state before applying a release.

The existing **Back up and upgrade this app** button queues the currently registered reviewed release. It does **not** automatically convert the Stage 1 or Stage 2 worklist into SQL. The queued request is tied to the exact release-manifest SHA-256, so the database worker refuses a different or modified plan.

## Required safeguards

Before applying a registered release, the operator worker makes verified COPY_ONLY/CHECKSUM backups of all three databases. It restores owned disposable copies, runs each migration there, checks integrity before and after, and records the expected schema fingerprints. The app enters maintenance only after all three rehearsals pass. Live results must match the rehearsed results.

If live application fails, the worker immediately attempts to restore all three retained source backups. The app stays suspended unless every restored plane passes its source-version verification. The Builder status and the operator receipt distinguish **Succeeded**, **Failed**, **Restore required**, and **Restored**; a failure is never reported as success merely because recovery was attempted.

Who runs PowerShell?

The PowerShell executor runs on the BuildWithHQ database-operator host. A SaaS builder or tenant user does not receive database credentials, SQL permissions, route configuration, or the migration files.

A golden database update does not silently update existing customer databases. Operators must still convert inventory findings into reviewed, immutable migrations and register the release before it can be approved.

No database credentials or SQL execution permissions are given to the browser. Builder access remains scoped to the owned SaaS app through the existing authorized API. Platform operators verify the stored-procedure boundary during the controlled release and restored-copy rehearsal; builders use the published release status and receipts.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/staged-database-upgrades.html).

---
title: "The + Debug drawer: see what your page did, safely"
section: "Builder Guide"
canonical_url: "https://support.buildwithhq.com/builder-guide/debug-drawer.html"
reviewed_at: "2026-09-14"
authority: Official
---

# The + Debug drawer: see what your page did, safely

Open the built-in diagnostic timeline on any page to see what it did, what failed, and why — without exposing customer data.

## In brief

- **Location:** Bottom of any page in an owned app
- **Access:** Authorized builder
- **Shows:** Safe outcomes, never raw data

Every page in your app carries a collapsed `+ Debug` control fixed to the bottom of the screen. Open it and you get an ordered timeline of the actions that page just took: navigation, form submits, database reads, and any AI calls it triggered, each with an outcome, a duration, and — when something failed — a safe reason and a way to follow it up. It's a diagnostic action timeline, not a browser console, packet inspector, SQL profiler, or unrestricted log viewer.

## Why it's there

Most of the time a builder finds out something is wrong from a customer complaint, long after the failure happened and with none of the context that would explain it. The debug drawer closes that gap: it shows you, in the moment, exactly which step of the page failed, how long it took, and a correlation ID that ties it to the same event your team (or BuildWithHQ support) sees on the authoritative Logs side — so you can investigate immediately instead of waiting for a report to work its way back to you.

## Opening it

Click `+ Debug` to open it. If the current page already has recorded failures, the collapsed control shows `Debug · N errors` without exposing any details until you open it. Opening the drawer starts a short-lived, server-issued session scoped to that exact page instance — it isn't a standing background logger, and it can't be extended indefinitely or resumed from another browser session.

## Reading the timeline

Filter the timeline by **All**, **Errors**, **Network**, **Actions**, **Database**, **Workers** or **AI** — which filters are available depends on your role. Each row shows the UTC time, a safe operation name, its outcome, duration, the build/component version that handled it, and its correlation ID. A failed row adds a safe failure code and an **Open problem** action that takes you straight to the same event on the authoritative app Logs surface, at the same correlation, even if that means signing back in to the Builder Console first.

For example, a page load might show a successful `page.definition.load` in 84 ms, followed by a `reservations.list` call that failed after 312 ms with the code `reservation_query_failed`, and then a retry that succeeded. That's usually enough on its own to tell you whether you're looking at a one-off blip or something worth investigating further — without reading a single line of a stack trace.

Opening a row's expandable diagnostic section shows its sequence position, full occurrence time, event ID, action ID and parent action ID (or an explicit root-action label), so you or a teammate can follow the exact causal chain — which action triggered which — across retries and asynchronous follow-ups.

## Closing and reopening problems

Once you've looked into a failure, close it from the drawer. Closing records who closed it and when, and the occurrence count at that moment — it does not delete or hide the underlying evidence. If the same failure happens again afterward, it reopens automatically with a higher occurrence count, so a recurring problem can't quietly stay marked closed while it keeps happening.

Note

Close, Resolve and Dismiss are lifecycle labels, not delete actions. Nothing in the drawer can erase recorded diagnostic history.

## What it deliberately never shows you

The drawer is built to be safe to look at — and safe to hand to someone else. It never captures request or response bodies, exception or SQL text, stack locals, URL query strings, headers, cookies, tokens, AI prompts or model output, customer records, secrets, connection strings, or physical database/server names. What you see is limited to identifiers, safe operation and outcome codes, timestamps, durations, versions, and correlation — enough to investigate, never enough to leak a customer's data by accident.

Important

A marketplace publisher only ever sees causally linked events for their own exact published version — never your tenants' identities or content. A platform operator's view is similarly scoped and fully audited. Nobody outside your own app sees your data through this feature.

## Exporting for support

Copy a correlation ID directly from any row, or export a sanitized diagnostic bundle for the whole session — the export shows exactly the same safe projection you can already see in the drawer, and every export is itself audited. That's usually all BuildWithHQ support needs to look at the same event on their side without you ever having to describe, screenshot, or paste anything sensitive.

## If Logs is temporarily unavailable

A drawer diagnostic outage never changes what the page actually does for your customer — collection failure can only produce a bounded warning, never a different business outcome. If the Logs plane itself is briefly unavailable, the drawer shows an honest `diagnostics temporarily unavailable` state rather than pretending the timeline is simply empty.

## From the CLI and your own tools

The same debug sessions are available through the Developer API with one of your builder keys: `bwhq debug start`, `events`, `timeline`, `tail`, `history` and `close` in the CLI, `BuildWithHQDesignClient` in the SDK, and a drop-in `DeveloperDebugDrawer` React component in the Developer Kit for pages you build yourself. A builder key acts as your app's owner, so sessions it starts appear in the owner's in-app drawer history, and the owner's sessions can be read from the CLI. Keep the key on a trusted server; the kit drawer talks to it only through your own server-side proxy.

## Session limits

Debug sessions expire on their own and are capped on events, rate and size. When a session expires, the drawer keeps the history you already saw, stops capturing new detail, and offers **Start new session** — which closes the old session and starts a fresh one rather than reviving the expired one.

Tip

Closing the drawer only stops the extra successful-action detail it samples while open. Errors are always recorded through the normal failure-observation path, whether the drawer is open or not — you won't miss a real failure by working with it closed.

## Still expanding

The drawer already covers page loads, their linked database reads, and AI calls like DataChat Ask across both the builder console and your live tenant pages. Deeper tracing into asynchronous worker and AI-job continuations, and dedicated marketplace-publisher and platform-operator views, are still being extended — so treat the drawer today as the fastest way to see what a page itself just did, with broader coverage arriving over time.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/builder-guide/debug-drawer.html).

---

# Section: Selling Templates

---
title: "From your app to the storefront"
section: "Selling Templates"
canonical_url: "https://support.buildwithhq.com/selling/overview.html"
reviewed_at: "2026-10-20"
authority: Official
---

# From your app to the storefront

Preview reference: The whole seller journey in one page: what you'll set up, in what order, and why each step exists.

## In brief

- **Availability:** Release-gated preview
- **Catalog model:** Templates, pages, modules, and bundles
- **Ledger model:** Sale price minus the platform fee
- **Listing model:** Draft, validated artifact, then offer

Marketplace preview

The seller journey described here is not an available production workflow. Paid checkout, refunds, payouts, and installation or upgrade require release acceptance. The material below is a preview reference, not instructions to perform financial tests or enable background workers.

These reference pages describe the seller catalog, exact-version artifacts, orders, and ledger model. They do not establish a working purchase, refund, payout, or installation journey. Marketplace financial and installation workflows remain release-gated; the model below is not confirmation that those actions are available in your deployment.

## The journey, end to end

1. **Become a seller** — open your storefront and connect payouts. [One-time setup.](becoming-a-seller.html)
2. **Prepare the work** — get the template to a published, validated version in your own account, with the licensing rules satisfied. [What “ready” means.](preparing-a-template.html)
3. **Register the artifact** — snapshot that exact version into your seller catalog, fingerprint and all. From this moment, what you sell is frozen and provable.
4. **Create the product and offer** — listing page, semantic version with release notes, then a priced offer. [Products, versions, and offers.](products-versions-offers.html)
5. **Activate** — the offer goes live once its checklist passes: published version, active seller, at least one active price.
6. **Get paid and iterate** — sales credit your ledger, eligible funds can be sent through Stripe Connect, and Stripe controls the connected account's payout timing; new versions ship without breaking existing buyers. [Getting paid](getting-paid.html)  and [after launch](after-launch.html).

Note

Everything on this path is permission-gated and audited like the rest of the platform: store actions require the marketplace store permission on your team role, payouts require the payout permission, and every step lands in your account's audit log.

## What you can sell

The same pipeline handles several product types — templates, individual pages, modules, bundles that install components in order, Harness Packs, integrations, and [appliances](../builder-guide/appliances-and-endpoints.html). This section uses templates as the running example; where another type differs, the page says so.

---

Capability review: 2026-10-20. [View the canonical guide](https://support.buildwithhq.com/selling/overview.html).

---
title: "Becoming a seller"
section: "Selling Templates"
canonical_url: "https://support.buildwithhq.com/selling/becoming-a-seller.html"
reviewed_at: "2026-10-20"
authority: Official
---

# Becoming a seller

Preview reference: Open your storefront and connect payouts — the one-time setup before anything can be listed.

## In brief

- **Availability:** Release-gated preview
- **Setup:** Storefront profile + payment onboarding
- **One per account:** Your account is your store
- **Status:** Pending until onboarding completes

Marketplace preview

The seller journey described here is not an available production workflow. Paid checkout, refunds, payouts, and installation or upgrade require release acceptance. The material below is a preview reference, not instructions to perform financial tests or enable background workers.

Selling starts with a **seller profile** — your public storefront identity — and payment onboarding so money can reach you.

## Your storefront

Choose a store slug (your storefront's address), a display name, a description, and a support email buyers can reach. One storefront per account; everything you sell lives under it, so its reputation compounds across your products.

Tip

Set the support email to something a teammate can also watch. Buyer questions answered fast become reviews; questions that sit become refunds.

## Connecting payouts

Payments run on Stripe. You'll complete a Stripe onboarding flow that verifies your identity and banking details — the same kind of onboarding any payment platform requires. Two switches flip as you progress:

- **Charges enabled** — buyers can pay for your products.
- **Payouts enabled** — money can be sent to your bank.

Your seller status moves from **Pending** to **Active** as onboarding completes. You can draft products while Pending, but offers can't go live — and payouts can't be requested — until you're Active with payouts enabled.

---

Capability review: 2026-10-20. [View the canonical guide](https://support.buildwithhq.com/selling/becoming-a-seller.html).

---
title: "Preparing a template for sale"
section: "Selling Templates"
canonical_url: "https://support.buildwithhq.com/selling/preparing-a-template.html"
reviewed_at: "2026-10-20"
authority: Official
---

# Preparing a template for sale

Preview reference: What “ready to sell” means: a published version, clean validation, and licensing you actually have.

## In brief

- **Availability:** Release-gated preview
- **Source:** A published version in your own account
- **Gate:** Validation-clean
- **Hard rule:** Only sell what you have the right to sell

Marketplace preview

The seller journey described here is not an available production workflow. Paid checkout, refunds, payouts, and installation or upgrade require release acceptance. The material below is a preview reference, not instructions to perform financial tests or enable background workers.

You don't upload files to the marketplace — you sell a **version that already exists** in your account's template library. Registering it as a seller artifact snapshots that exact version, with its cryptographic fingerprint, into your catalog. Buyers get precisely what you registered, forever; your later edits become *new* versions, never silent changes to what someone already bought.

## The quality gate

The version you register must be published and pass its validation. For tenant pages, the current publication gate requires zero page-content errors and zero warnings. Resolve both before preparing the template, and review the template version's own validation report before registering it for sale.

## The licensing rule — read this one twice

Important

You may only sell work you have the right to sell: your own original designs, AI-generated work, or components from genuinely permissive (MIT-style) sources. Commercial template kits are prohibited — converting a purchased theme into platform blocks changes its format, not its license, and reselling it would infringe. This protects you as much as the marketplace: you are the seller of record.

## What makes a template sell

- **Complete beats pretty** — templates ship with pages, menus, and user types; a buyer should have a working product minutes after install, not a homepage and a to-do list.
- **Real content in the preview** — lorem ipsum hides exactly the layout problems buyers will find on day one.
- **Install notes that respect the buyer** — each version carries release notes and install notes; say what's included, what to configure first, and what's intentionally left open.

---

Capability review: 2026-10-20. [View the canonical guide](https://support.buildwithhq.com/selling/preparing-a-template.html).

---
title: "Products, versions, and offers"
section: "Selling Templates"
canonical_url: "https://support.buildwithhq.com/selling/products-versions-offers.html"
reviewed_at: "2026-10-20"
authority: Official
---

# Products, versions, and offers

Preview reference: The three-layer listing model, the four billing models, and the activation checklist.

## In brief

- **Availability:** Release-gated preview
- **Three layers:** Product → versions → offers
- **Billing models:** Free, one-time, recurring, usage
- **Activation model:** The activation checklist

Marketplace preview

The seller journey described here is not an available production workflow. Paid checkout, refunds, payouts, and installation or upgrade require release acceptance. The material below is a preview reference, not instructions to perform financial tests or enable background workers.

Listings have three layers, and keeping them straight makes everything else obvious:

| Layer | What it is | Changes over time? |
| --- | --- | --- |
| **Product** | The listing: name, slug, category, descriptions, preview image, visibility (public, unlisted, or private). | Yes — it's your marketing surface. |
| **Version** | A semantic release of the underlying artifact, with release notes and install notes. | Append-only — new releases, never edits. |
| **Offer** | The commercial terms attached to a version: billing model plus one or more prices. | Drafted, then activated. |

## Billing models

- **Free** — price must be zero. Free products build storefront reputation and funnel buyers to your paid work.
- **One-time** — pay once, own the version. The natural fit for templates.
- **Recurring** — a subscription, for products that deliver ongoing value (kept-current template lines, services).
- **Usage** — metered billing with included units and an overage rate; requires at least one active meter before the offer can go live. Built for appliances and integrations more than templates.

Prices are set per currency, so one offer can carry a USD and a EUR price side by side.

Note

Free trials on paid offers aren't available yet — offers currently activate with trials set to zero. It's on the marketplace billing roadmap.

## The activation checklist

An offer flips from draft to live only when everything lines up, and the platform checks rather than trusts:

1. The product version is **published** (not draft).
2. Your seller profile is **Active**.
3. The offer has **at least one active price** (zero for free, positive for paid).
4. Usage offers have an **active meter**.

Each failed check tells you exactly which requirement is unmet — fix it and activate again.

---

Capability review: 2026-10-20. [View the canonical guide](https://support.buildwithhq.com/selling/products-versions-offers.html).

---
title: "Getting paid"
section: "Selling Templates"
canonical_url: "https://support.buildwithhq.com/selling/getting-paid.html"
reviewed_at: "2026-10-20"
authority: Official
---

# Getting paid

Preview reference: Order math, the seller ledger, Stripe Connect payout submission, and provider-controlled delivery timing.

## In brief

- **Availability:** Release-gated preview
- **Ledger model:** Sale price minus the platform fee
- **Ledger status:** Pending versus eligible funds
- **Delivery model:** Provider-controlled timing

Marketplace preview

The seller journey described here is not an available production workflow. Paid checkout, refunds, payouts, and installation or upgrade require release acceptance. The material below is a preview reference, not instructions to perform financial tests or enable background workers.

## The math on every order

Each order records the full breakdown permanently: the subtotal, the platform fee, and **your net** — computed at sale time from your account's fee rate, so a later fee change never rewrites history. Refunds are tracked on the same order, and a refund reverses the corresponding credit in your ledger.

## Your ledger

Every financial event — sale, refund, adjustment — is a signed entry in your seller ledger. Your balance is simply the sum, per currency, which means it's fully explainable: any balance can be decomposed into the exact entries that produced it.

## Pending, available, and paid are different states

Your seller ledger distinguishes funds that are still pending from funds eligible for a payout request. This is accounting state, not a promise that money will reach a bank on a fixed BuildWithHQ schedule. Once an eligible transfer is submitted through the connected account, Stripe Connect controls processing and bank-delivery timing. Review the current estimate and any account requirements in Stripe.

## Requesting a payout

With an Active profile, payouts enabled, and a connected Stripe account, request any amount up to your available balance in a currency. The platform verifies the balance at the moment of the request — concurrent requests cannot double-spend it — and submits the transfer through Stripe Connect. BuildWithHQ records request and provider status; Stripe determines the processing and bank-arrival timeline.

| If a payout is refused | It means |
| --- | --- |
| “Payouts are not enabled” | Stripe onboarding isn't complete — finish it in your seller settings. |
| “Exceeds the available balance” | Part of your ledger balance is not currently eligible. Check pending versus available before requesting another transfer. |
| “Payout permission denied” | Your team role lacks the payout permission — an owner can grant it. |

---

Capability review: 2026-10-20. [View the canonical guide](https://support.buildwithhq.com/selling/getting-paid.html).

---
title: "Managing products after launch"
section: "Selling Templates"
canonical_url: "https://support.buildwithhq.com/selling/after-launch.html"
reviewed_at: "2026-10-20"
authority: Official
---

# Managing products after launch

Preview reference: Shipping new versions, honoring existing buyers, refunds, and retiring products well.

## In brief

- **Availability:** Release-gated preview
- **New versions:** Never disturb existing buyers
- **Refunds:** Reverse your ledger credit
- **Retiring:** Stops new sales, not existing installs

Marketplace preview

The seller journey described here is not an available production workflow. Paid checkout, refunds, payouts, and installation or upgrade require release acceptance. The material below is a preview reference, not instructions to perform financial tests or enable background workers.

## Shipping improvements

Register the improved artifact version, add it to the product with release notes, and attach an offer. Because sold versions are frozen snapshots, existing buyers are never surprised: what they installed keeps working exactly as bought, and adopting your new version is their choice — delivered through the same [block-level upgrade flow](../builder-guide/templates-forking.html)  they use for any template, so their customizations survive your improvements.

Tip

Release notes are marketing to your existing buyers. A clear “what's new and why you'd want it” converts installed-base into upgrade revenue — and into reviews.

## Refunds and disputes

Refunds are recorded against the original order and reverse the matching credit in your ledger. The maturity window on funds exists precisely so most refunds resolve before money moves. Fast, generous support through your storefront's support email is the cheapest dispute prevention there is.

## Retiring a product

Retiring stops new sales; it does not reach into buyers' apps. Anyone who bought remains entitled to what they bought. Retire the listing, keep supporting existing buyers through the support channel, and the storefront reputation you built carries to your next product.

---

Capability review: 2026-10-20. [View the canonical guide](https://support.buildwithhq.com/selling/after-launch.html).

---

# Section: Inspirations to Build From

---
title: "Build a white-label agency CRM"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/agency-crm.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a white-label agency CRM

An agency platform with isolated client sub-accounts, pipelines, and communication history — sold under your own brand.

## In brief

- **Category:** Agency & reseller platforms
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Agency account and client sub-accounts
- Contacts and companies
- Deal pipelines and stages
- Appointment calendar
- Unified communication history (email, SMS, calls)
- Landing pages and forms
- Reputation-request records
- Client billing and usage

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Pipeline Kanban board
- Contact directory with activity timeline
- Unified inbox per client account
- Landing-page builder
- Client billing dashboard

## Automation: when a review request is triggered

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. Wait until the job/appointment record marks complete
2. Send a review-request message on the client's chosen channel
3. Log the outreach on the contact's timeline
4. If no response in N days, send one follow-up
5. Notify the account owner when a review lands

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Agency / all-in-one marketing platforms |
| --- | --- |
| Market size (directional) | Marketing & sales software overall is a $70B+ category; the agency all-in-one niche is a small but fast-growing slice of it. |
| Who actually buys | Marketing agencies and MSPs reselling to local businesses |
| Where incumbents price | Agency all-in-one platforms typically run roughly $100–500/mo per agency, with unlimited or high sub-account counts at the top tier. |
| Suggested entry pricing | **$150–400/mo per agency, or $30–60/mo per client sub-account** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Per-sub-account pricing — revenue scales with your reseller's own growth, the single best-aligned model in this list
- White-label domain and branding as a paid tier
- Usage-metered SMS and email volume on top of the base fee
- Done-for-you niche template packs (dental, HVAC, legal) sold through your [storefront](../selling/index.html)
- AI assistant seats priced per user, since each one replaces measurable labor

## The BuildWithHQ angle

The classic version of this product keeps every reseller on a centrally controlled master template — an update anywhere is an update everywhere, whether a reseller wants it or not. Here, each reseller gets their own [fork](../builder-guide/templates-forking.html): they customize fields, layouts, workflows, and connections freely, and a future improvement to your master template arrives as a choice they adopt block-by-block, never a change forced on their running business.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/agency-crm.html).

---
title: "Build a HubSpot-style CRM and marketing system"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/hubspot-crm.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a HubSpot-style CRM and marketing system

Contacts, deals, and lifecycle stages tied together with the automations that actually move a pipeline.

## In brief

- **Category:** Sales & marketing operations
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Contacts and companies
- Deals, pipelines, and stages
- Activities and meetings
- Forms
- Email templates and sequences
- Lifecycle stage and lead score fields
- Dashboards

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Deal pipeline board
- Contact record with full activity history
- Meeting scheduler
- Form builder
- Sales and marketing dashboard

## Automation: core lifecycle automations

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. Form submitted → create or update the contact
2. Lead score crosses a threshold → assign to sales
3. Meeting booked → advance the deal to the next stage
4. Customer replies → stop the active sequence
5. Deal marked won → create an onboarding project

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | CRM + marketing automation |
| --- | --- |
| Market size (directional) | CRM is the largest enterprise software category at roughly $70–100B globally and still growing double digits. |
| Who actually buys | SMB and mid-market sales and marketing teams |
| Where incumbents price | Mainstream CRM suites run roughly $20–150/seat/mo, with marketing tiers priced separately by contact volume. |
| Suggested entry pricing | **$25–75/seat/mo, or $300–1,500/mo flat for a vertical-specific edition** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Contact-volume tiers on the marketing side — the standard second axis beyond seats
- Advanced reporting and attribution as a paid upgrade
- AI lead scoring and email drafting as a per-seat add-on
- Implementation and data-migration services, often 1–3× first-year subscription
- Vertical editions (real estate, insurance, clinics) at a premium over the generic build

## The BuildWithHQ angle

Because contacts, deals, and pipeline stages are ordinary modules and fields, the line between “CRM data” and “everything else in your business” disappears. An onboarding project created on deal-close isn't a webhook into a separate product — it's the same [connected record system](../end-user/how-everything-connects.html)  your CRM already lives in, so the project shows up on the deal, the deal on the project, both directions, automatically.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/hubspot-crm.html).

---
title: "Build a Salesforce-style custom business application"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/salesforce-custom.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a Salesforce-style custom business application

Not a Salesforce clone — a custom-object database with the permission depth serious operations need, built without starting from scratch.

## In brief

- **Category:** Sales & marketing operations
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Fully custom objects and fields per your business, not a fixed schema
- Record relationships across any two modules
- Role-based and field-level permissions
- Location-based access scoping
- Workflow actions and outbound webhooks
- Immutable activity history on every record

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Configurable list and detail views per object
- Role-scoped dashboards
- Record activity timeline
- Admin screens for fields, permissions, and workflows

## Automation: a permission-sensitive record update

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A user attempts to edit a field
2. The [security layer](../trust/security-architecture.html)  checks their role, location, and field-level grant before the write is allowed
3. On success, the change is written to the immutable activity history
4. Any bound workflow reacts to the new value
5. Anyone without the read grant simply never sees the field existed

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Custom business applications / low-code platforms |
| --- | --- |
| Market size (directional) | Enterprise low-code and custom application platforms represent a $25–35B category, growing faster than traditional CRM. |
| Who actually buys | Operations leaders replacing spreadsheets or escaping per-seat enterprise CRM costs |
| Where incumbents price | Enterprise platform licenses commonly land at $75–300/seat/mo, which is exactly the pain you're selling against. |
| Suggested entry pricing | **$40–100/seat/mo, or $2,000–10,000/mo for an org-wide license** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Org-wide flat pricing as the headline differentiator against per-seat incumbents
- Field-level security and audit features gated to a compliance tier
- Custom object and workflow limits by tier, raised as customers grow
- Configuration and admin retainers — recurring services revenue
- Sandbox/staging environments as a paid add-on for larger accounts

## The BuildWithHQ angle

Field-level security here isn't an add-on module bolted onto a general database — it's the same [permission and encryption model](../builder-guide/secure-fields.html)  that governs every other feature on the platform, including AI. A custom object you build this afternoon inherits it automatically; there's no separate security configuration to remember for “the custom stuff.”

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/salesforce-custom.html).

---
title: "Build a visual sales pipeline"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/pipedrive-crm.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a visual sales pipeline

The clearest starting project: a Kanban pipeline, a contact directory, and the drag-to-advance automation that makes a sales CRM feel alive.

## In brief

- **Category:** Sales & marketing operations
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Organizations and contacts
- Leads and deals
- Pipelines and stages
- Activities and notes
- Products
- Files
- Users and teams

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Pipeline Kanban board
- Lead inbox
- Contact directory with activity timeline
- Deal detail page
- Product catalog
- Sales dashboard
- Personal activity queue

## Automation: when a deal is dragged to a new stage

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. Validate the user has permission to move it
2. Update the stage
3. Record the previous and new stage on the activity history
4. Create an activity-history entry for the move itself
5. Check whether the deal needs a next action and flag it if so
6. Notify the assigned salesperson
7. Run any configured webhook or email step for that stage
8. Recalculate pipeline metrics on the dashboard

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Visual sales CRM (SMB) |
| --- | --- |
| Market size (directional) | The SMB slice of the CRM category — the largest by customer count, most price-sensitive by deal size. |
| Who actually buys | Small sales teams, typically 3–25 reps |
| Where incumbents price | SMB-focused visual CRMs price at roughly $15–100/seat/mo across tiers. |
| Suggested entry pricing | **$20–50/seat/mo** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Per-seat is the natural model here; land small and grow with the team
- Pipeline and automation limits by tier
- Email/calendar sync and sequencing as the mid-tier upgrade
- AI deal-risk scoring as the premium tier's headline feature
- Vertical pipeline templates sold separately for instant time-to-value

## The BuildWithHQ angle

This is the best first build precisely because every piece of it — the board, the drag interaction, the cascading updates — is ordinary page, module, and workflow configuration. Nothing here needs your container. It's the fastest way to feel the platform's core loop before reaching for custom code.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/pipedrive-crm.html).

---
title: "Build a sales engagement and sequencing system"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/sales-engagement.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a sales engagement and sequencing system

Multi-step outreach sequences with branching, reply detection, and automatic enrollment — the engine behind Outreach- and Salesloft-style tools.

## In brief

- **Category:** Sales & marketing operations
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Sequences with ordered steps
- Step types: email, call, manual task, wait condition
- Contact enrollment and automatic unenrollment
- A/B message variants
- Reply classification
- Sales task queue
- Meeting and opportunity attribution

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Sequence designer
- Personal task queue
- Enrollment and performance dashboard

## Automation: sequence step progression

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A contact enrolls in a sequence
2. Each step fires on schedule: send email, place call task, or wait
3. An inbound reply is classified
4. If it's a positive or negative reply, unenroll automatically
5. Log the outcome and attribute it to the right deal

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Sales engagement / sequencing |
| --- | --- |
| Market size (directional) | A $3–6B category sitting on top of CRM, with strong per-seat economics because it's tied directly to quota-carrying reps. |
| Who actually buys | Sales development and inside sales teams |
| Where incumbents price | Sales engagement tools commonly price at $75–165/seat/mo — buyers accept high per-seat cost because it maps to rep productivity. |
| Suggested entry pricing | **$50–120/seat/mo** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Per-seat pricing is well-established here and buyers expect it — don't undercharge
- Message-volume or dialer-minute metering on top of seats
- AI reply classification and message generation as a premium tier
- Conversation analytics and coaching as an upsell to sales management
- CRM integration depth as a tier gate (basic sync vs. bidirectional)

## The BuildWithHQ angle

Email and SMS delivery come from providers you connect through [API connections](../builder-guide/external-api-connections.html)  — the platform never claims to be a mail server. What it owns is the sequence logic, the records, the permissions, and the analytics, which is the part that's actually yours to differentiate.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/sales-engagement.html).

---
title: "Build a work management platform"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/work-management.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a work management platform

One reusable foundation — projects, tasks, and views — that becomes Basecamp, Trello, Asana, monday.com, ClickUp, or Wrike depending on which views and fields you emphasize.

## In brief

- **Category:** Project & work management
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Workspaces and projects
- Lists
- Tasks and subtasks
- Checklists
- Statuses and assignees
- Due dates and dependencies
- Comments and files
- Milestones
- Time entries
- Client-facing users

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- List view
- Kanban board
- Calendar view
- Timeline / Gantt view
- Personal task view
- Portfolio dashboard
- Workload dashboard

## Automation: a task moving through its lifecycle

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A task's status changes
2. Dependent tasks are checked and unblocked if their blocker just completed
3. The assignee is notified
4. The activity history records the change
5. The portfolio dashboard recalculates

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Project & work management |
| --- | --- |
| Market size (directional) | Roughly $7–12B globally and one of the most crowded categories in software — which is why vertical specialization matters more than feature parity. |
| Who actually buys | Teams of 10–500, plus agencies managing client work |
| Where incumbents price | Horizontal work management tools cluster at $8–25/seat/mo; a few price flat per team. |
| Suggested entry pricing | **$12–30/seat/mo generic, or $40–80/seat/mo for a vertical edition** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Vertical editions are the whole play here — a construction or legal edition commands multiples of generic pricing
- Client-portal seats priced separately (or free, to drive land-and-expand)
- Time tracking and resource planning as the mid-tier upgrade
- Portfolio and workload dashboards gated to the management tier
- Guest/collaborator seat packs for agencies with many external stakeholders

## The shared foundation, six ways

Build the data model and the five shared views once, then differentiate by configuration, not by rebuilding: emphasize projects, discussions, and client portals for a Basecamp feel; simple boards and checklists for Trello; milestones and portfolios for Asana; configurable columns and automation recipes for monday.com; nested hierarchy and interchangeable views for ClickUp; request forms and resource allocation for Wrike. Six products, one foundation, six template packs.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/work-management.html).

---
title: "Build an engineering issue tracker"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/issue-tracking.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build an engineering issue tracker

One issue-tracking foundation, configured two ways: strict and reportable like Jira, or fast and minimal like Linear.

## In brief

- **Category:** Project & work management
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Teams and projects
- Issues and issue types
- Statuses and workflow transitions
- Sprints or cycles
- Releases and epics
- Dependencies and estimates
- Comments and development links
- Customer requests

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Backlog
- Board (sprint or cycle)
- Triage inbox
- Velocity and burndown reports
- Command-palette-driven issue creation

## Automation: an issue moving through a workflow transition

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. Validate the transition is legal for this issue type
2. Update status
3. Record the transition in activity history
4. Update sprint/cycle burndown metrics
5. Trigger any configured release or notification step

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Engineering issue tracking |
| --- | --- |
| Market size (directional) | A few billion dollars globally, heavily consolidated around two or three incumbents — best approached as a vertical or embedded play rather than head-on. |
| Who actually buys | Software teams; or product companies embedding issue tracking in their own tool |
| Where incumbents price | Issue trackers price at roughly $8–20/seat/mo, with steep discounts at volume. |
| Suggested entry pricing | **$10–25/seat/mo, or embed it inside a broader product rather than selling standalone** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Honest assessment: competing head-on here is hard — the strongest version is embedded issue tracking inside a vertical platform you already sell
- Customer-request intake portals as a paid module (connects support to engineering)
- Advanced reporting: velocity, burndown, cycle time as a management tier
- Compliance-grade audit history for regulated engineering orgs
- Per-project pricing for agencies running many small client projects

## Two configurations, one foundation

Configure strict workflow transitions, custom issue types, and detailed backlogs for a Jira-style tool aimed at process-heavy teams; configure a minimal issue form, a triage inbox, automatic archiving, and keyboard-first navigation for a Linear-style tool aimed at speed. Source control stays where it belongs — GitHub or GitLab connect in as [API connections](../builder-guide/external-api-connections.html), not a rebuilt code host.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/issue-tracking.html).

---
title: "Build a relational data app like Airtable"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/airtable.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a relational data app like Airtable

Arguably the platform's own best demo: user-defined tables and fields, multiple views, and the automations that turn a spreadsheet into an application.

## In brief

- **Category:** Data application builders
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- User-defined tables and fields
- Linked records across tables
- Lookups and rollups
- Formula fields
- Public shareable views

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Grid view
- Kanban view
- Gallery view
- Calendar view
- Timeline view
- Forms

## Automation: a record update cascading through links

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A linked record's field changes
2. Any rollup or lookup depending on it recalculates
3. A bound automation runs if the new value matches its condition
4. Anyone viewing a public share sees the update, filtered to what that share exposes

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | No-code relational databases |
| --- | --- |
| Market size (directional) | The no-code/low-code tooling market is $20–30B+ and expanding quickly as non-developers build more internal software. |
| Who actually buys | Ops teams, agencies, and technical non-developers |
| Where incumbents price | Relational no-code tools price at roughly $20–45/seat/mo, with record and automation-run limits as the second axis. |
| Suggested entry pricing | **$25–60/seat/mo — you can justify the premium with capabilities the incumbent structurally lacks** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- This is the strongest upsell story in the section: start at parity pricing, then charge for what the incumbent can't do at all
- Server-side custom logic and your own secured API as a developer tier
- [Container and Postgres access](../builder-guide/container-and-postgres.html)  as a premium tier — a genuine capability jump, not a limit raise
- Record volume and automation-run tiers (the standard second axis)
- Deployable branded applications built on the same data — an offering the incumbent has no answer for

## The BuildWithHQ angle

This is where the comparison stops being fair — in the platform's favor. Airtable's ceiling is Airtable: no server-side logic, no secure API of your own, no deployable application around the data. Here, the exact same relational modeling opens onto full custom pages, real server-side workflow actions, your own secured API, and — when a formula field genuinely isn't enough — [your own container and Postgres database](../builder-guide/container-and-postgres.html). You can start exactly like Airtable and grow into something Airtable structurally cannot become.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/airtable.html).

---
title: "Build a hierarchical project sheet like Smartsheet"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/smartsheet.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a hierarchical project sheet like Smartsheet

Row hierarchies, formulas, and Gantt views for teams who think in spreadsheets but need approvals and cross-sheet reporting.

## In brief

- **Category:** Data application builders
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Hierarchical rows (parent/child)
- Formula fields
- Approval-request records
- Cross-sheet report definitions

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Grid with row hierarchy
- Gantt view
- Form intake
- Cross-sheet report dashboard

## Automation: a form-driven approval

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A form submission creates a row
2. An approval request is generated and routed to the right approver
3. On approval, the row's status updates and dependent rows are notified
4. The change is recorded in cell-level history

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Spreadsheet-style project execution |
| --- | --- |
| Market size (directional) | Overlaps work management, skewing more enterprise; buyers are often PMO and operations groups with real budget. |
| Who actually buys | PMO, construction, manufacturing, and operations teams |
| Where incumbents price | Grid-based enterprise project tools price at roughly $9–35/seat/mo, with enterprise agreements far above that. |
| Suggested entry pricing | **$20–50/seat/mo, with enterprise licenses negotiated annually** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Approval workflows and cell-level history as the compliance tier — regulated buyers pay for provable history
- Cross-sheet reporting and portfolio rollups gated to management seats
- Resource management and capacity planning as an add-on
- Form intake volume tiers for high-submission customers
- Annual enterprise agreements with implementation services attached

## The BuildWithHQ angle

Build this after your grid and formula components are mature — the specialized part of this product is calculation depth, not data modeling, and it's worth getting the formula engine right before promising it.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/smartsheet.html).

---
title: "Build a document-database hybrid like Coda"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/coda.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a document-database hybrid like Coda

Documents that embed live database views, buttons, and formulas — software that reads like a page instead of a spreadsheet.

## In brief

- **Category:** Data application builders
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Document pages
- Embedded database views inside a page
- Formula fields
- Dropdown and control fields

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Rich document pages with embedded, filterable table views
- Interactive buttons that trigger workflow actions
- Record-detail layouts embedded inline

## Automation: a button-triggered action

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A user clicks a button embedded in the document
2. The bound workflow action runs (update a record, call an external API, notify someone)
3. The embedded view refreshes to reflect the change in place

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Document–database hybrids |
| --- | --- |
| Market size (directional) | A newer, smaller slice of the productivity market, but growing — buyers are teams frustrated by the doc/spreadsheet/app split. |
| Who actually buys | Startup and mid-market teams building internal tools without engineering |
| Where incumbents price | Doc-database hybrids price at roughly $10–35/seat/mo, often with free viewer/editor asymmetry. |
| Suggested entry pricing | **$15–40/seat/mo, with free read-only seats to drive adoption** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Free viewer seats, paid editor seats — the classic model for this category and it works
- Automation-run and external API call volume as usage tiers
- Published/shared external docs as a paid feature (public-facing use has real value)
- Template packs for specific workflows (OKRs, hiring, product planning)
- Team-wide governance and permissions as the enterprise tier

## The BuildWithHQ angle

This is a strong showcase for the platform's [page and data-binding model](../builder-guide/page-editor.html)  specifically — it proves the same block system that builds an ordinary business app can also build software that doesn't feel like database software at all.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/coda.html).

---
title: "Build a multi-brand support desk like Zendesk"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/support-desk.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a multi-brand support desk like Zendesk

Ticketing with SLA timers, routing, and knowledge management — a strong early build because the data model is straightforward and the commercial case is obvious.

## In brief

- **Category:** Customer support & experience
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Customers and organizations
- Tickets and ticket messages
- Internal notes
- Agents and teams
- SLA definitions
- Macros and tags
- Satisfaction surveys
- Knowledge articles

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Ticket queue by brand, category, or priority
- Ticket detail with message thread
- Agent workload dashboard
- Knowledge base

## Automation: SLA-aware ticket routing

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A new ticket is routed by brand, category, priority, or agent skill
2. An SLA timer starts
3. A warning fires as the response deadline approaches
4. Simultaneous conflicting edits are prevented via the page/record edit lock
5. On resolution, a satisfaction survey sends automatically
6. Repeat questions get flagged as knowledge-base candidates

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Customer support / help desk |
| --- | --- |
| Market size (directional) | Roughly $10–20B and one of the most reliably budgeted categories — support tooling is rarely cut, because the queue never stops. |
| Who actually buys | Support teams; multi-brand companies; MSPs supporting many clients |
| Where incumbents price | Help desks price at roughly $20–115/agent/mo across tiers, with AI features increasingly metered separately. |
| Suggested entry pricing | **$30–75/agent/mo** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Multi-brand support is a genuine premium tier — companies running several brands pay well to avoid several instances
- SLA management and escalation rules as a mid-tier gate
- AI-suggested replies and auto-triage, priced per agent or per resolution
- Knowledge base and customer portal as a bundled upsell
- CSAT/analytics dashboards for support leadership

## The BuildWithHQ angle

Multi-brand routing is a natural fit for the platform's module and permission model: each brand is a scoped view over the same ticket data rather than a separately maintained instance, so agents, SLAs, and reporting stay unified even as the public-facing brand splits apart.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/support-desk.html).

---
title: "Build a customer messaging platform like Intercom"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/intercom.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a customer messaging platform like Intercom

A website messenger, shared inbox, and AI-answered support — grounded in your own knowledge base and gated by real permissions.

## In brief

- **Category:** Customer support & experience
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Customer profiles
- Conversations (routed the same way as any inbox line)
- Announcements and banners
- Onboarding tour definitions
- Satisfaction prompts

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Embeddable website messenger
- Shared inbox
- Customer profile with full history
- Knowledge-base search

## Automation: an AI-answered support conversation

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A customer message arrives on the messenger channel
2. The AI assistant searches the knowledge base for a grounded answer
3. If confident and permitted, it drafts a reply for approval; if not, it routes to a human
4. The exchange is logged on the customer's record

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Conversational customer engagement |
| --- | --- |
| Market size (directional) | Sits between support and marketing across a combined $15B+ opportunity; the AI-resolution model is actively reshaping pricing here. |
| Who actually buys | SaaS and e-commerce companies with high inbound volume |
| Where incumbents price | Conversational platforms price at roughly $40–140/seat/mo, and increasingly meter AI resolutions separately (often near $1 per resolved conversation). |
| Suggested entry pricing | **$40–100/seat/mo plus AI resolution metering** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Per-resolution AI pricing is where this category is heading — it prices on outcomes, which customers accept readily
- Messenger customization and branding as a paid tier
- Product tours and onboarding flows as a separate module
- Knowledge-base grounding quality as the premium differentiator
- Volume tiers on monthly active contacts reached

## The BuildWithHQ angle

This is where the platform's [AI assistant model](../builder-guide/goclaw-in-depth.html)  earns its keep: support manuals and FAQs are embedded and searched, but every answer is filtered by the same permission model as everything else — a document a customer shouldn't see can't leak into an answer to them, and every AI response stays inside the approve-before-send discipline you already trust for internal use.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/intercom.html).

---
title: "Build a conversational form builder like Typeform"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/typeform.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a conversational form builder like Typeform

One-question-at-a-time forms with branching logic and payment steps — an excellent early project with a JSON-simple data model.

## In brief

- **Category:** Forms, surveys & research
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Form definition as structured content
- Per-question validation and visibility rules
- Hidden URL-parameter fields
- Submission records

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- One-question-at-a-time renderer
- Custom ending pages
- Submission analytics with abandonment tracking
- Embeddable form widget

## Automation: a branching, validated submission

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A question's answer is captured
2. Conditional logic decides the next question shown
3. A calculated field updates from prior answers
4. On completion, a payment step runs if configured
5. The submission becomes a record other modules can react to

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Forms & data collection |
| --- | --- |
| Market size (directional) | A smaller category (low single-digit billions) but with unusually low build cost and very broad demand — a strong first product. |
| Who actually buys | Marketers, researchers, and any team collecting structured input |
| Where incumbents price | Conversational form tools price at roughly $25–90/mo by response volume rather than seats. |
| Suggested entry pricing | **$20–80/mo by response volume** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Response-volume pricing rather than seats — matches how the value actually accrues
- Payment collection inside forms (take a small percentage or charge for the feature)
- Custom branding and domain removal as the classic first upgrade
- Advanced logic, calculations, and answer piping as a pro tier
- Analytics and abandonment insights for conversion-focused buyers

## The BuildWithHQ angle

Because a submission is an ordinary record the moment it lands, a completed form isn't a dead end in a forms tool — it can create a contact, kick off a workflow, or land directly in a pipeline, with the same permission and audit guarantees as any other data entering the system.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/typeform.html).

---
title: "Build an enterprise survey platform like Qualtrics"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/qualtrics.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build an enterprise survey platform like Qualtrics

Advanced branching, scoring, and role-restricted reporting for research-grade surveys — with clear limits on what stays in scope.

## In brief

- **Category:** Forms, surveys & research
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Advanced survey definitions (matrix questions, answer piping, branching)
- NPS / CSAT / CES score fields
- Role-restricted dashboard definitions
- Distribution schedules

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Survey renderer with branching and piping
- Role-scoped results dashboard
- Cross-tab report view

## Automation: score-triggered follow-up

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A response is scored (NPS/CSAT/CES)
2. A low score creates a support ticket automatically
3. Sentiment analysis runs on free-text responses
4. Results roll into the role-restricted dashboard on schedule

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Experience management / enterprise survey |
| --- | --- |
| Market size (directional) | A $10–20B category with genuinely enterprise budgets — the highest average contract values in this list. |
| Who actually buys | Enterprise research, HR, and customer-experience teams |
| Where incumbents price | Enterprise experience platforms are quoted annually, commonly $5,000–100,000+/year depending on scope. |
| Suggested entry pricing | **$10,000–60,000/year for a focused vertical or departmental edition** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Annual contracts, not monthly — this buyer expects and prefers it, and it transforms your cash flow
- Response volume and distribution tiers
- Role-restricted dashboards for executive stakeholders as a premium seat type
- Sentiment and text analytics as an AI add-on
- Implementation, survey design, and analysis services — often as large as the license

## The BuildWithHQ angle

Be precise about scope here: this covers the operational core well — branching, scoring, role-gated reporting, automated escalation. Conjoint analysis and advanced statistical modeling are specialized research tooling, best positioned as external analytics integrations rather than implied as a standard feature.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/qualtrics.html).

---
title: "Build a multi-channel marketing automation platform"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/marketing-automation.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a multi-channel marketing automation platform

Segments, flows, and campaign attribution — one blueprint that covers Klaviyo, Mailchimp, and ActiveCampaign-style automation.

## In brief

- **Category:** Marketing automation
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Contacts and consent records
- Audience segments
- Custom events
- Campaigns
- Automation flows with wait and branch steps
- Email/SMS templates
- Frequency-limit rules
- Conversion and attribution records

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Segment builder
- Flow designer
- Campaign performance dashboard
- Attribution report

## Automation: an event-triggered automation flow

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A custom event fires (purchase, cart abandonment, signup)
2. The contact enters the matching flow
3. Branching and wait steps execute on schedule
4. Frequency limits are checked before every send
5. Conversions attribute back to the originating campaign

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Marketing automation |
| --- | --- |
| Market size (directional) | Roughly $6–12B, with pricing conventionally driven by contact list size rather than seats. |
| Who actually buys | E-commerce brands and B2B marketing teams |
| Where incumbents price | Marketing automation platforms scale from about $30/mo at small list sizes into thousands per month at scale. |
| Suggested entry pricing | **$50–500+/mo scaling with contact volume** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Contact-volume pricing is the category standard and scales automatically with customer success
- SMS as a metered add-on with margin on every message
- Deliverability tooling and dedicated sending as a premium tier
- Revenue attribution reporting — the feature that justifies the whole spend to a CFO
- Vertical playbook packs (e-commerce, SaaS onboarding, events)

## The BuildWithHQ angle

The platform orchestrates the logic — segments, flows, attribution, frequency limits — while delivery runs through connected providers (SendGrid, Mailgun, Postmark, Amazon SES, Twilio, or others) via [API connections](../builder-guide/external-api-connections.html). You own the intelligence layer; you don't need to become a mail transfer agent to ship it.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/marketing-automation.html).

---
title: "Build a real-time engagement platform like Braze or Drift"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/engagement-platforms.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a real-time engagement platform like Braze or Drift

The advanced layer on top of marketing automation: real-time triggers, in-app messaging, and live chatbot playbooks.

## In brief

- **Category:** Marketing automation
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Real-time event triggers
- In-app banner and modal definitions
- Chatbot playbook scripts
- Account-based alert rules
- Multivariate test definitions

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- In-app message composer
- Chatbot playbook builder
- Live test performance dashboard

## Automation: a real-time in-app trigger

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A qualifying event fires inside the customer's app in real time
2. The matching in-app message or chatbot playbook is selected
3. A frequency cap is checked before display
4. The customer's app renders the message via the platform's frontend SDK
5. The interaction is logged back for attribution

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Real-time customer engagement |
| --- | --- |
| Market size (directional) | The enterprise tier of marketing automation; contracts are large, sales cycles long, and buyers technical. |
| Who actually buys | Enterprise growth and lifecycle marketing teams with in-house apps |
| Where incumbents price | Enterprise engagement platforms are typically $50,000–150,000+/year, priced on monthly active users. |
| Suggested entry pricing | **$25,000–100,000/year on MAU tiers** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- MAU-based annual contracts — the enterprise standard in this category
- In-app messaging SDK access as a tier gate
- Multivariate testing and experimentation as a premium module
- Real-time event throughput tiers
- Dedicated success management, which enterprise buyers expect and will pay for

## The BuildWithHQ angle

Position this as the advanced tier once your marketing automation foundation is solid — it adds real-time delivery and in-app rendering on top of the same segments, flows, and attribution you already built, rather than a separate system to maintain.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/engagement-platforms.html).

---
title: "Build an API orchestration and enrichment tool like Clay"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/clay.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build an API orchestration and enrichment tool like Clay

Spreadsheet rows with enrichment columns that call external providers, with waterfall fallback logic and full credit tracking — a strong demo of the platform as an orchestration layer.

## In brief

- **Category:** Integration-heavy projects
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Rows as records
- Enrichment columns configured to call specific providers
- Waterfall provider order (try A, fall back to B)
- Credit-usage tracking
- Reusable workflow templates

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Spreadsheet-style grid with live enrichment columns
- Credit-usage dashboard

## Automation: a waterfall enrichment run

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A row is queued for enrichment
2. The first provider in the waterfall is called via an API connection
3. If it fails or returns nothing, the next provider is tried
4. AI can be used to synthesize a research summary from the returned data
5. Credit usage is decremented and logged

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | GTM data orchestration |
| --- | --- |
| Market size (directional) | A young, fast-growing niche within sales tooling — small today, but expanding quickly as teams automate research. |
| Who actually buys | Sales and growth teams doing outbound at scale |
| Where incumbents price | Orchestration tools price on credits, commonly $150–800+/mo by credit volume. |
| Suggested entry pricing | **$100–600/mo on credit tiers** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Credit-based pricing is the model here — buy provider data wholesale, resell at margin inside credits
- AI research and summarization consuming credits at a higher rate
- Prebuilt enrichment workflow templates as a paid library
- Higher-tier waterfall access (more providers in the fallback chain)
- Managed list-building services for teams without the time to configure

## The BuildWithHQ angle

The data itself has to come from licensed providers you connect — the honest positioning is an orchestration layer, not a data owner. What's genuinely yours to build is the waterfall logic, the credit accounting, and the reusable templates around it.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/clay.html).

---
title: "Build a prospecting and enrichment portal"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/prospecting-portal.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a prospecting and enrichment portal

The application layer over sales intelligence data — filters, target lists, and alerts — built on top of providers who own the underlying data network.

## In brief

- **Category:** Integration-heavy projects
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Prospect filter definitions
- Company profile records
- Target lists
- Org-chart relationships
- Job-change alert rules
- Email-verification status fields

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Prospect search and filter screen
- Company profile page
- Target-list builder
- Alert feed

## Automation: a job-change alert

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A connected provider reports a tracked contact's job change
2. The alert is created and routed to the owning rep
3. The target list updates automatically
4. A CRM export or sync runs if configured

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Sales intelligence |
| --- | --- |
| Market size (directional) | A $4–8B category dominated by data owners; your value is the application layer and workflow, not the data itself. |
| Who actually buys | Sales teams needing contact and company intelligence |
| Where incumbents price | Sales intelligence runs from about $50/seat/mo for self-serve tools to $15,000–40,000+/year for enterprise data contracts. |
| Suggested entry pricing | **$50–150/seat/mo, with your data cost passed through in tiers** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Price transparently around your data cost — margin comes from the workflow layer, not from marking up records
- Credit tiers for enrichment and export volume
- Job-change and trigger alerts as a premium feature (high perceived value, low delivery cost)
- CRM sync depth as a tier gate
- Team list-sharing and territory management for larger accounts

## The BuildWithHQ angle

Be direct about what this is: the application layer — filters, lists, alerts, CRM export — over data owned by providers like Apollo or People Data Labs, connected via API. Don't imply the platform owns a proprietary contact database; it doesn't, and the honest framing sells better anyway.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/prospecting-portal.html).

---
title: "Build a call intelligence platform like Gong"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/call-intelligence.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a call intelligence platform like Gong

Call records, transcripts, and coaching — with the heavy media processing kept where it belongs.

## In brief

- **Category:** Integration-heavy projects
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Call records
- Transcripts and speaker segments
- AI-generated summaries
- Coaching scorecards and comments
- Keyword flags
- Deal-risk indicators

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Call detail page with transcript and timeline
- Coaching scorecard view
- Deal-risk dashboard

## Automation: post-call processing

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A recorded call lands in the system
2. A container-hosted or connected service performs speech-to-text
3. The AI assistant summarizes the call and extracts action items
4. Keyword and risk flags are applied
5. Linked CRM records (the deal, the contact) update automatically

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Revenue intelligence / conversation analytics |
| --- | --- |
| Market size (directional) | Roughly $2–5B and growing fast, with high per-seat prices because buyers tie it directly to revenue outcomes. |
| Who actually buys | Sales leadership at teams with 10+ reps |
| Where incumbents price | Conversation intelligence platforms commonly run $1,200–1,800/seat/year plus a platform fee. |
| Suggested entry pricing | **$80–150/seat/mo, or annual contracts with a platform fee** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Annual per-seat contracts with a platform fee is the established shape — buyers don't blink at it
- Transcription minutes as a metered pass-through with margin
- AI coaching scorecards as the premium tier
- Deal-risk analytics for sales leadership (the executive-budget feature)
- CRM auto-update as an integration tier

## The BuildWithHQ angle

Recording, storage, and speech-to-text are specialized media infrastructure — the natural fit is a [container-hosted component](../builder-guide/container-and-postgres.html)  or a connected service, not something to rebuild in the visual layer. What the platform owns well: the records, the CRM linkage, the AI summarization, and the coaching workflow around the output.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/call-intelligence.html).

---
title: "Build a team messaging system like Slack"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/team-messaging.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a team messaging system like Slack

Channels, threads, and searchable history are a natural fit — but be honest about what production-grade real-time messaging actually requires.

## In brief

- **Category:** Integration-heavy projects
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Channels and threads (modeled as records, so they inherit permissions and search)
- Messages
- Reactions
- File attachments

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Channel view with threads
- Direct message view
- Search across message history

## Automation: a message posted to a channel

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A message is created as a record on the channel
2. It's indexed for search immediately
3. Mentioned users are notified
4. Any bound workflow (e.g., keyword-triggered alert) can react to it

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Team messaging |
| --- | --- |
| Market size (directional) | A few billion dollars, but effectively won by incumbents — the realistic play is embedded messaging inside your own vertical product. |
| Who actually buys | Realistically: your own product's users, not a standalone messaging buyer |
| Where incumbents price | Standalone team chat prices around $8–15/seat/mo, which is hard to beat without a wedge. |
| Suggested entry pricing | **Bundle it into a vertical platform rather than pricing standalone** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Be honest about this one: standalone is a losing fight — messaging is a retention feature inside a product you already sell
- Compliance retention and eDiscovery for regulated industries — the one place standalone can win
- Guest/client channels for external collaboration
- Message history retention tiers
- Workflow-triggered channel automation as a differentiator

## The BuildWithHQ angle

Channels, threads, permissions, and search are genuinely solid ground here — they're the same connected-record system as everything else. Be upfront that production-grade presence, typing indicators, and message fanout at real chat-app scale call for dedicated real-time infrastructure (WebSocket/SignalR-class), and that voice/video huddles are better left to an external service. This is a strong advanced-tier build, not a first project.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/team-messaging.html).

---
title: "Build a video messaging app like Loom"
section: "Inspirations to Build From"
canonical_url: "https://support.buildwithhq.com/inspirations/video-messaging.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a video messaging app like Loom

The SaaS wrapper around video — folders, comments, and AI summaries — with capture and streaming left to specialized infrastructure.

## In brief

- **Category:** Integration-heavy projects
- **Build from:** Modules, workflows, and the page editor
- **Extend with:** Your container when you outgrow the visual tools

## Data model

Build these as [modules and custom fields](../builder-guide/menus-user-types.html)  — no schema migration, no code required to add a field or a relationship:

- Video records and folders
- Permissions per video or folder
- Comments and reactions
- Chapters
- Viewer-analytics events

## Pages

Compose these in the [page editor](../builder-guide/page-editor.html)  from data-bound blocks, or start from a template pack and customize from there:

- Video library with folders
- Video detail page with comments and chapters
- Viewer-analytics dashboard

## Automation: post-upload processing

Model this as a [workflow](../builder-guide/workflows.html)  — each bullet is naturally one step, run automatically on the trigger:

1. A video finishes uploading
2. An AI summary and chapter markers are generated
3. The video is permissioned per your access rules
4. Viewer events (opens, watch time) are logged for analytics

## Market and pricing

Read these as directional

Market sizes and competitor prices move constantly, and published figures vary widely by source and methodology. Treat the numbers below as order-of-magnitude orientation for deciding what to build — not as researched inputs for a pitch deck or a pricing page. Verify current figures before either.

| Segment | Async video messaging |
| --- | --- |
| Market size (directional) | A smaller category (low single-digit billions) with strong attach rates when bundled into a larger product. |
| Who actually buys | Sales, support, and internal comms teams |
| Where incumbents price | Video messaging tools price at roughly $12–30/seat/mo. |
| Suggested entry pricing | **$15–35/seat/mo, or bundle as an add-on to a broader platform** |

## Building in more value

Where the margin actually lives — the upgrades and add-ons worth designing in from the start rather than bolting on later:

- Bundling beats standalone here — attached to a CRM or support product, it lifts the whole subscription's price
- Storage and video-retention tiers (your infrastructure cost passed through)
- AI summaries, chapters, and transcripts as a premium feature
- Viewer analytics and CTAs for sales use cases
- Custom branding and branded viewer pages

## The BuildWithHQ angle

Browser capture, transcoding, and streaming delivery belong to specialized video infrastructure you connect to — attempting to rebuild that inside the platform would be effort spent on a solved problem. What's worth building here is everything around the video: organization, permissions, comments, AI summaries, and analytics, which is exactly where the platform's connected-record model is strongest.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/inspirations/video-messaging.html).

---

# Section: Using Your App

---
title: "About this section (for builders)"
section: "Using Your App"
canonical_url: "https://support.buildwithhq.com/end-user/for-builders-white-label.html"
reviewed_at: "2026-09-14"
authority: Official
---

# About this section (for builders)

How to reuse these end-user guides under your own brand.

## In brief

- **Audience:** Builders
- **Purpose:** Meta
- **License:** Reuse freely in your apps

This section helps your customers use their application. You can link to these pages or adapt their content for your own help center. The public site carries BuildWithHQ branding, and the account-administration and developer-kit instructions include platform-specific names. Before sharing a branded copy, replace those names, sign-in addresses, screenshots, and support contacts, and include only features enabled in your app.

Tip

Answering user questions is your first support tier; these pages exist so most questions never reach you — and the ones that do never reach us.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/end-user/for-builders-white-label.html).

---
title: "Signing in and your account"
section: "Using Your App"
canonical_url: "https://support.buildwithhq.com/end-user/signing-in.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Signing in and your account

Access your workspace, reset a password, and keep your account secure.

## In brief

- **Audience:** End users
- **Time:** 3 min
- **Applies to:** All applications

You sign in at the web address your organization gave you, with your work email and password.

## Forgot your password?

Use the reset link on the sign-in page. You'll get an email with a one-time link — it works once and expires, so request a fresh one if it's been a while.

## Locked out?

Too many wrong attempts locks sign-in briefly for your protection. Wait 15 minutes and try again; if you still can't get in, contact your administrator — they can confirm your account status.

## Keeping your account safe

- Never share your password; administrators can create accounts for colleagues who need access.
- If two-factor authentication is offered, turn it on and store your recovery codes safely.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/end-user/signing-in.html).

---
title: "Administer your tenant account"
section: "Using Your App"
canonical_url: "https://support.buildwithhq.com/end-user/account-administration.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Administer your tenant account

Invite hosted users, manage external users, DataRoles, locations, User Type menus, and the synchronized developer-kit account overlay.

## In brief

- **Who:** Active account owners
- **Data scope:** One AppAccount only
- **Account overlay:** Generated on request

An active account owner can open **Admin** from the application top bar. This is the operating console for that tenant account—not the SaaS builder control plane. Every read and write derives the SaaS app, AppAccount, user, DataRoles, and database route from the signed-in server identity. The browser cannot choose another account by supplying an ID.

## What an account owner can see

- Account status, primary contact information, creation date, and current module inventory.
- Total and active users, each user’s User Type, assigned DataRoles, location scope, status, and most recent successful login.
- Active and inactive DataRoles, their record capabilities, AI-read/export/trust/billing flags, and named action-permission keys.
- Locations, codes, addresses, time zones, managers, ordering, and active state.
- Builder-approved shared User Types, their current menus and pages, and any account-owned menu override.

## What an account owner can change

- Invite a hosted user by email with a selected User Type, DataRoles, and location scope.
- Add a real external/headless TenantUser, selecting its User Type, DataRoles, and either specific locations or all-location scope.
- Activate or deactivate non-owner users with optimistic revision protection.
- Create DataRoles and explicitly select record, AI, export, billing, and named action permissions. Trust-record and disbursement controls are not available as enforced tenant capabilities yet.
- Create locations and deactivate an unassigned location. An assigned location is refused rather than silently changing a user’s security meaning.
- Assign only User Types the SaaS builder enabled for tenant assignment, and narrow or reorder a shared menu only when the builder enabled overrides for that User Type.

Important

The account owner cannot deactivate the active owner or a DataRole assigned to an active owner. A concurrent edit returns a conflict and must be reloaded; it is never silently overwritten.

## External users versus hosted sign-in

The **Add user** form creates a passwordless external identity for delegated/headless API use. The owner supplies the stable external user ID used by their own identity provider. BuildWithHQ stores no invented password and does not return a reusable per-user secret. Their backend exchanges or delegates identity through the supported user-token path, and every operation runs through that TenantUser’s real DataRole and location envelope.

The **Invite a hosted user** form is an explicit, separate choice. BuildWithHQ sends an expiring, single-use link. The recipient establishes their own password, then signs in through the hosted application. The invitation snapshots the selected User Type, DataRoles, and locations, and applies them atomically only after acceptance.

Note

The raw invitation secret is never stored. Email links keep it in the browser URL fragment so it does not enter ordinary HTTP access logs, and resolve/accept send it only in a CSRF-protected POST body. Resend rotates the secret; revoke, expiry, or successful acceptance prevents reuse.

An invitation can link an existing passwordless external user with the same email or create one intended TenantUser. External-only users remain unable to use hosted sign-in unless the owner deliberately invites them.

## Synchronize the Developer Kit account overlay

The canonical Developer Kit ZIP is a public website download; downloading it requires no tenant permission or API key. Protected API calls made with the kit require valid credentials and are limited by their scopes and the caller’s server-verified identity and record permissions. To add one organization’s private account overlay, run `tools/sync_account_overlay.py` with a short-lived tenant session. The server requires owner access or delegated Developer Kit and design capabilities before returning Account Overlay 2.1.0. The original **Admin → Developer kit → Download ZIP** action provides the same protected, account-specific overlay for offline import; it is not the public kit download. The overlay contains:

- `account.json` with this account’s safe SaaS/AppAccount identity and authentication mode, but no credential;
- `capabilities.json` with all 23 published platform capabilities;
- `contracts/operations.json` with all 242 published tenant-runtime operations and their exact methods and routes;
- `catalog/lego-modules.json` with the ID-addressed module schema routes currently supported for declarative composition;
- the current User Type/menu presentation contract, effective account page JSON, and active binding metadata (never connector secrets);
- working same-origin account, module, Lego-catalog, and declarative-composite TypeScript clients;
- copyable React account-administration, live-module and Lego-composite panels, plus Contacts directory and Work Orders board samples that load real catalog IDs rather than fixtures;
- database schema/release and catalog fingerprints for compatibility checks;
- pinned package/typecheck configuration, an offline validator, and a SHA-256 manifest covering every generated file.

Built-in capabilities are enabled by default. Pages and menus control where a capability is pinned; they are not feature switches. Separately purchased or installed modules retain their own activation lifecycle. Publication in the ZIP is still not an authorization grant: every request reapplies the current TenantUser, DataRole, location, User Type, record and action-policy checks.

The archive never contains a tenant access token, password, SQL connection, provider credential, raw customer row, placeholder binding, or a way to widen permissions. The included AppAccount ID is configuration—not authorization. A current tenant session is still required on every call, and the browser must never receive a server-side draft, live, CLI, or MCP credential.

## Install and verify the overlay

```
$env:BWHQ_TENANT_ORIGIN = 'https://your-tenant.example.com'
$env:BWHQ_TENANT_ACCESS_TOKEN = '<short-lived tenant session bearer>'
python .\tools\sync_account_overlay.py
```

The tenant token is used only for the authorized account-overlay download and is never written to disk. Draft and live Developer API keys belong in trusted backend secret storage; they authorize only their permitted API operations and are never substitutes for the tenant session required by account-overlay sync or exposed to browser code.

```
npm install
npm run check
```

`npm run check` type-checks the clients and React starters, verifies every manifest hash, checks the account-scoped catalog shape, and refuses placeholder bindings or credential-shaped content. Choose an operation from `contracts/operations.json`, pass its route, query, and body values to `TenantModuleClient.invoke`, and render the authorized JSON directly or through `LiveModulePanel`.

## When to synchronize again

Run the tool with `--replace` after an installed-module, shared User Type/menu, account menu, page, binding, database upgrade, or tenant API contract change. Compare `compatibility.json` and the manifest in source control rather than assuming an old overlay still represents the running account.

## Support lane manager

The editable organization-owned email/SMS lane manager is included in the current kit. See [support lanes, installation and API contracts](../api/support-lanes.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/end-user/account-administration.html).

---
title: "Your inbox"
section: "Using Your App"
canonical_url: "https://support.buildwithhq.com/end-user/your-inbox.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Your inbox

Work conversations and optional support tickets from every channel in one place.

## In brief

- **Audience:** End users
- **Time:** 5 min
- **Related:** Notifications

The inbox gathers conversations from every connected channel — email, text messages, website inquiries, and messages from colleagues — so you work from one screen instead of five apps.

## What you see

You see conversations routed to you personally, to a role you hold, or to shared team lines. If a conversation you expect is missing, it's likely routed to someone else — ask your administrator about routing rather than assuming it's lost.

## Working a conversation

Open a conversation to see its full history across channels. Reply in place — your reply goes out through the same channel the message arrived on.

## Support tickets

If your organization has enabled ticketing for an email address or SMS line, new conversations received on that channel receive a permanent ticket key such as `SUP-000123` or `SMS-000123`. Use the **Support tickets** view to focus on those conversations. The key stays with the thread through assignment, replies, resolution, and reopening.

The ticket's resolution state tells the team what should happen next: New, Open, Waiting on customer, Waiting internally, Snoozed, Resolved, or Closed. A new reply reopens a resolved or closed Inbox ticket so it returns to the attention queue. Closing the native Conversation is different and can start a new SMS thread. Channels without ticketing enabled continue to behave like ordinary inbox channels; disabling ticketing does not erase existing ticket identities.

Account owners use **Email and SMS ticketing setup** to choose the channel and a 2–12 character letter/number prefix. SMS requires a configured inbound phone line and authenticated provider setup; enabling ticketing does not purchase numbers or send messages.

## Follow-ups

Set a follow-up on any conversation to get nudged if it goes quiet. The bell at the top of the screen counts everything waiting for your attention.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/end-user/your-inbox.html).

---
title: "AI suggestions and approvals"
section: "Using Your App"
canonical_url: "https://support.buildwithhq.com/end-user/ai-suggestions.html"
reviewed_at: "2026-09-14"
authority: Official
---

# AI suggestions and approvals

What the assistant does, what it never does without you, and how to review its work.

## In brief

- **Audience:** End users
- **Control:** You approve everything
- **Related:** Your inbox

If your organization has enabled the AI assistant, it prepares work for you: draft replies, summaries, and suggested next steps based on your conversations.

## You are always the decision

The assistant never sends, changes, or creates anything on its own. Its proposals wait in your approval queue, where you can edit, approve, or dismiss each one. An unreviewed proposal simply waits — nothing happens without you.

## Reviewing well

- Read drafts before approving; the assistant is fast, you are accountable.
- Edit freely — an edited approval sends your version, not the original draft.
- Dismiss anything unhelpful; you're not required to act on suggestions.

## Rate what it does

After an action runs, you can rate it and leave a note — and even without rating, what you do with each suggestion (approve it, edit it first, or dismiss it) quietly teaches the system what good looks like for you. Editing a draft before approving is especially useful feedback: it shows exactly what the suggestion should have been. None of this is busywork with no destination — it's read by the people tuning the assistant, and it's why the suggestions get better over time.

## If the assistant seems to stop

Assistants have a daily action budget. Late in a busy day it may pause until tomorrow — that's normal and resets automatically.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/end-user/ai-suggestions.html).

---
title: "Your insights feed"
section: "Using Your App"
canonical_url: "https://support.buildwithhq.com/end-user/insights-feed.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Your insights feed

What the AI has noticed in your data, ranked by priority — and how to keep the feed yours.

## In brief

- **Audience:** End users
- **Time:** 4 min
- **Related:** AI suggestions and approvals

The insights feed is where the application surfaces things it noticed on its own: a customer who's gone quiet, a job trending late, a pattern worth a look. Each insight tells you what was found, why it might matter, and — often — a suggested next step.

## Reading the feed

Insights are ordered by priority, so the top of the feed is the AI's best guess at what deserves you first. Each one shows how confident the AI is and how serious the finding would be if it's right — a low-confidence, high-severity item is worth a skeptical look; a high-confidence, low-severity one might just be housekeeping.

## Make it yours

- **Pin** an insight to keep it at the top while you work it.
- **Snooze** one to make it disappear until later — it comes back when the time passes.
- **Hide** what's not useful; hiding is yours alone and never removes it for teammates.

Acting on an insight or dismissing it moves it out of your open feed. Some insights expire on their own when they stop being timely.

## Why a teammate sees different insights

Insights follow the same permissions as the records they came from. If you and a colleague cover different locations or roles, your feeds will differ — that's the application showing each of you only what you're entitled to see, not a sync problem.

Note

Insights are suggestions, not instructions. The AI ranks and recommends; deciding is your job, and dismissing a finding you know is wrong makes the feed better.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/end-user/insights-feed.html).

---
title: "Records, fields, and search"
section: "Using Your App"
canonical_url: "https://support.buildwithhq.com/end-user/records-and-data.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Records, fields, and search

Find, view, and edit information — and why some fields behave differently.

## In brief

- **Audience:** End users
- **Time:** 5 min
- **Related:** Protected fields

Your application organizes information as records — customers, jobs, orders, whatever your organization tracks. Search finds records across everything you're allowed to see.

Records don't live in isolation — they link to each other across every module, and those connections are visible from both ends. See [How everything connects](how-everything-connects.html).

## Why you might not see something

What you can see and edit follows the permissions your administrator set. Two people can search the same word and get different results; that's the permission model working, not a bug.

## Protected fields

Some fields are protected: their values show as hidden until you explicitly choose to reveal them, and **they don't appear in search results**. These fields hold sensitive information your organization has chosen to encrypt. If you can't find a record by a value you know it contains, that value may be in a protected field — search by something else.

## Approvals on records

Some processes pause a record for approval. While a record is waiting on someone's sign-off, editing is locked; it unlocks the moment the decision is made.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/end-user/records-and-data.html).

---
title: "Coordinate work in ActiveWorkplace"
section: "Using Your App"
canonical_url: "https://support.buildwithhq.com/end-user/active-workplace.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Coordinate work in ActiveWorkplace

Pin a record, follow its connected work, coordinate participants, and review its history.

## In brief

- **Start with:** A record you can access
- **Tracks:** Connected work and responsibility
- **History:** Playback is read only

ActiveWorkplace is a shared coordination view around a record and the related records connected to it. It does not replace the customer, case, file, project, conversation, or other item you started from.

[How the module works](../first-class-modules/active-workplace.html) [Your Inbox](your-inbox.html) [Records and data](records-and-data.html)

## Pin a Record

1. Open ActiveWorkplace and search the visible Record list.
2. Select the Record you want to coordinate.
3. Choose **Pin to ActiveWorkplace**.

If an active workplace already exists for that root, the app opens the existing one instead of creating a duplicate. Search results include only Records currently available to you.

## Read the workplace

- **Record Pulse** shows whether work is Active, Waiting, At Risk, Stale, Dormant, or Resolved.
- **Tracking graph** groups the pinned Record and currently visible connected Records by depth.
- **Participants** shows people, GoClaw assistants, and workflows plus their stated responsibility.
- **Activity** shows meaningful updates and system transitions with attribution and time.
- **Inbox attention** calls attention to work that became At Risk or Stale.

## Update Pulse and activity

Use **Waiting** when work is blocked by a date, reply, or dependency, and add a useful reason. Post an update when meaningful progress occurs. Use **Dormant** for intentionally inactive work and **Resolved** when coordination is complete. Your app may limit these controls according to your current permission.

## Add participants

Select an eligible User, GoClaw, or Workflow and describe what it is responsible for. Assignment does not grant new access: participants can still see or act only within their own existing permission and approval rules.

Note

A GoClaw may monitor and prepare work, but a material or customer-facing action still follows the app's normal action permission and approval policy.

## Use Graph Playback

Choose a retained date/time and select **Play back**. A prominent **Graph Playback · read only** banner appears. The page reconstructs retained workplace, graph, participant, and activity state, but still uses what you are allowed to access today.

Choose **Return to current** to leave historical mode. You cannot change Pulse, post an update, add/remove participants, refresh the graph, launch a workflow, or run a GoClaw action while playback is open.

Important

Playback is historical context, not a way to restore old access. A Record removed from your current DataRole or location scope stays unavailable even if you could see it at the historical time.

## If something is missing

A graph branch, participant, or event may be absent because the current relationship scope is bounded, the Record was removed, or your current DataRole/location no longer includes it. Ask your app administrator about access; do not create a duplicate Record to make it appear.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/end-user/active-workplace.html).

---
title: "How everything connects"
section: "Using Your App"
canonical_url: "https://support.buildwithhq.com/end-user/how-everything-connects.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How everything connects

Every piece of information is a record, records link across every module, and relationships are always visible from both sides — so you never have to guess what belongs to what.

## In brief

- **The rule:** Everything is a record; records link
- **Both directions:** A link is visible from either end
- **No guessing:** Related items show themselves

Most software makes you keep the map in your head: the file is in one place, the meeting in another, the customer in a third, and remembering that they belong together is your job. This application works the other way. Underneath everything — contacts, jobs, meetings, files, conversations, tasks, whatever your organization tracks — is one connecting layer, and every item on it can be linked to any other. Once things are linked, the connection travels with *both* of them, everywhere, forever.

## One example, followed all the way through

Say there's a site-visit meeting on the calendar. Attached to it: a floor plan file and the customer it's for.

- Open the **meeting** — you see the floor plan and the customer right there.
- Later, you find the **floor plan** through search instead. Opening it shows you it belongs to that site visit and that customer — you arrived from a completely different direction, and the context came with it.
- Open the **customer** — the meeting and the file appear among their related items, alongside every other conversation, task, and document tied to them.

Nobody filed anything three times. One link, made once, is visible from every end of it. That's the whole trick, and it applies across every module — a task can point at an invoice, a conversation at a job, a file at all of them.

## Relationships are two-way, always

This is the part worth internalizing: **there is no such thing as a one-way attachment.** Attaching a file to a meeting is the same act as connecting that meeting to the file. So the question “where is this used?” — the one that's unanswerable in a folder full of documents — always has an answer here. Open anything, look at its related items, and you're looking at everything it's part of.

## Where you'll see it

- **Related items on every record** — open anything and its connections are listed: what it belongs to, and what belongs to it, across every module.
- **The inbox** — conversations are records too, so an email thread can be linked to the customer and job it concerns, and shows up from their side just like a file would.
- **Insights and follow-ups** — when the application surfaces something (an [insight](insights-feed.html), a reminder), it arrives attached to the record it's about, with that record's connections one click away.

Tip

When you create something, take the two seconds to link it to what it belongs to. That one link is what makes it findable from every direction later — it's the highest-return habit in the whole application.

## Connections respect permissions

Related items follow the same access rules as everything else. If a meeting is linked to a document you don't have access to, that document simply doesn't appear in your related view — and following connections outward never reaches anything you couldn't open directly. Two colleagues looking at the same record can legitimately see different related items; that's the permission model working, exactly as it does in [search](records-and-data.html).

## Why this beats folders

A folder can hold a file in exactly one place. A record can be connected to a meeting, a customer, a job, and an invoice at once — because those are relationships, not locations. The file isn't *in* the meeting; it's *connected to* it, and to everything else it genuinely relates to. When someone asks “what's the story on this customer?”, the answer isn't a scavenger hunt across five modules — it's one screen of related items, assembled by the system, filtered to what you're allowed to see.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/end-user/how-everything-connects.html).

---
title: "What's New and Favorites"
section: "Using Your App"
canonical_url: "https://support.buildwithhq.com/end-user/whats-new-and-favorites.html"
reviewed_at: "2026-09-14"
authority: Official
---

# What's New and Favorites

Catch up on changes across any date range, and follow the records you care about.

## In brief

- **What's New:** Changes, filtered by date range
- **Favorites:** Your followed records
- **Digests:** Daily by default

Two features exist to answer the question every busy user has: *what happened while I wasn't looking?* What's New answers it broadly; Favorites answers it for the records you personally care about.

## What's New

What's New shows changes across everything you can see, filtered by a date range you pick — this morning, since last Friday, the two weeks you were away. Choose the range and the view assembles what was created and changed inside it, newest first.

Tip

Back from time off? Set the range to your absence and work top to bottom. It beats scrolling every module hoping to notice differences.

Like every list in the application, What's New is permission-filtered: it shows changes to records you're entitled to see, and nothing else. Two teammates with the same date range can legitimately see different results.

## Favorites

Any record can be favorited. Your favorites list is yours — name each entry what you like, drag them into your own order, and **pin** the few you live in so they stay on top.

### Following changes

A favorite can do more than bookmark: turn on **change tracking** for one and you'll be notified when it changes, without visiting it. You control the rhythm per favorite — how often you're told (daily digest by default, so a busy record becomes one summary instead of a drip of pings) and through which channel (email by default).

Note

If a favorite disappears from your list, your access to that record changed — favorites only show records you can currently see. The bookmark isn't lost; it returns if access does. Ask your administrator if it's unexpected.

## Using them together

A rhythm that works: favorites with tracking for the handful of records you're accountable for, and a weekly What's New pass over a seven-day range for everything else. Between the two, nothing important happens quietly.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/end-user/whats-new-and-favorites.html).

---
title: "Notifications"
section: "Using Your App"
canonical_url: "https://support.buildwithhq.com/end-user/notifications.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Notifications

What the bell counts and how to keep it useful.

## In brief

- **Audience:** End users
- **Time:** 2 min
- **Related:** Your inbox

The bell in the top bar counts what needs your attention: inbox conversations awaiting review, approvals waiting on you, and follow-ups that have come due.

## Getting to zero

Open the bell to see the list; each entry links straight to the thing that needs you. Acting on it clears it — there's no separate “mark as read” housekeeping to do.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/end-user/notifications.html).

---
title: "Back up and download your data"
section: "Using Your App"
canonical_url: "https://support.buildwithhq.com/end-user/download-your-data.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Back up and download your data

Your data is yours — the account owner can create a complete, verified copy of it at any time. It is never trapped here.

## In brief

- **Who:** The account owner only
- **What:** Everything: records, files, AI data, history
- **Verified:** Every file ships with checksums

A promise this application makes plainly: **your data is yours, and it is not held hostage.** The account owner can create an independent, complete, verified copy of the account's data at any time, for any reason — a scheduled backup habit, a compliance requirement, or simply because owning your data means being able to hold it in your hands.

## Who can do it

Only the **account owner**. The download control appears in account settings for the owner alone — and more importantly, the restriction is enforced on the server for every step of the process, not just by hiding a button. The system confirms, from the signed-in identity itself, that the requester is the active owner of this specific account before anything is prepared or released. No one can request it on the owner's behalf, and nothing in the request can point it at a different account, because the request doesn't carry an account at all — the server already knows whose data the owner owns.

## What you receive

One archive, named with your account and a timestamp, containing:

- **Your database** — every record across the whole account: your core business data, your AI data (including what the AI has generated for you), your operational data, and your history and logs.
- **Your files** — documents, images, and attachments, organized in folders.
- **A manifest** — a machine-readable inventory of what the archive contains and when it was made.
- **Checksums** — a fingerprint for every file, so you (or your IT team, or an auditor) can verify the archive is complete and untampered, today or years from now.

Tip

Make it a habit, not an event. A periodic download filed with your other backups costs minutes and means your continuity plan never depends on any single vendor — including this one.

## Data export and application export are separate

The routine archive described on this page is the **data export**: portable customer tables, values, files, AI data, operational history, and audit history. Builders can separately export the application's versioned JSON and JSON Schema definitions for pages and workflows. Keeping these packages separate makes it possible to back up customer data frequently without placing platform runtime code or credentials into every routine archive.

**No secrets travel in either export.** Password hashes, API keys, tokens, and other credential-bearing values are stripped or represented only by non-secret references. Credentials must be re-established in the destination environment during a migration or continuity restoration.

Note

Only your account's data is ever included. The export is scoped to your account at the database level — the same isolation that governs everything else here governs what can leave.

## Send backups to storage you control

Customers can also configure customer-owned Amazon S3 storage for restore bundles containing the database, files, schemas, settings, manifest, and checksums. The customer controls the bucket, access rules, retention, versioning, and optional Object Lock. This provides a backup copy that does not depend on BuildWithHQ remaining the only holder of the files.

## Use the export to leave or rebuild

You can use an export as a verified backup, import the data into your own reporting or replacement system, or use it with the application-definition export and continuity runtime to restore the application outside BuildWithHQ. Because each customer has an isolated database, restoration is performed for that customer without separating their records from a shared customer-data database. Read [Business continuity and application portability](../trust/business-continuity-and-portability.html).

## Why this matters

Most software makes data export an off-boarding concession — something you fight for on the way out. Here it's a standing feature of being a customer: exercisable anytime, by you, without asking permission or opening a ticket. Data ownership you can't exercise isn't ownership; this is the exercising. For analytics, the separate [Snowflake export](../builder-guide/snowflake-analytics-sync.html)  copies selected organization log metadata after connection verification and explicit enablement. Automatic export additionally requires an available scheduled worker and an enabled schedule; it is not a complete data backup.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/end-user/download-your-data.html).

---

# Section: Developer Platform

---
title: "API Map"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/api-map.html"
reviewed_at: "2026-09-14"
authority: Official
---

# API Map

Route inventory for native modules, Developer API operations and Build This recipes.

## In brief

- **First-class:** 25 capabilities
- **Build This:** 18 products
- **Surfaces:** Tenant runtime + Developer API

Status: generated for Developer Kit **1.20.70** from current repository contracts. Public OpenAPI SHA-256: `5f9bf4cee2ede9c6715ab4ec81822690e1c0cfd954571abb48f62d624e9527f2`; platform OpenAPI SHA-256: `67769f799e55d571518adfe4f63c60cc8a1bb9853e1c4f1256304469787eefab`.

Shipped operations catalog (`catalog/operations.json`) SHA-256: `b2c80609e287117773d179b7ed3c7412ce9a1fad46f162ef2c935b50369f6b93`.

This is a source-generated inventory. Its fingerprints describe these inputs; immutable package publication and deployment are recorded separately.

This document inventories the two application-facing HTTP surfaces without treating client-supplied identity as authorization:

- **Tenant runtime** routes begin with `/api/` and are used by rendered, authenticated SaaS pages.
- **Developer API** routes begin with `/v1/apps/{saasAppId}/` and are used by live-app or delegated-user integrations according to each OpenAPI operation's scopes.

The first section includes every route under the exact API base paths of all 25 documented first-class capabilities. The Build This section includes every route in the canonical generated recipe and every additional OpenAPI operation explicitly named by the runnable solution manifest. When a Build This product composes a first-class capability, the complete capability route set remains in section 1 and is linked from the product entry instead of being copied repeatedly.

Excluded from section 1 are control-plane, authentication, health, payment-support, and product-specific renderer routes that are not one of the 25 documented first-class capabilities. The portable runtime renderer routes are documented explicitly below; other excluded routes appear in section 2 only when a canonical Build This recipe or solution manifest references them.

## What you need beyond this inventory

The first-class and Build This tables answer the native product-surface question. A complete headless SaaS also needs the supporting platform contracts below.

**App design: pages, validation, history and publishing**

| Method | Route | OpenAPI operationId |
| --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/design/authorization` | `developerAppDesignAuthorizationGet` |
| `GET` | `/v1/apps/{saasAppId}/design/pages` | `developerAppDesignPagesList` |
| `POST` | `/v1/apps/{saasAppId}/design/pages` | `developerAppDesignPagesCreate` |
| `GET` | `/v1/apps/{saasAppId}/design/pages/{pageKey}` | `developerAppDesignPagesGet` |
| `PUT` | `/v1/apps/{saasAppId}/design/pages/{pageKey}/draft` | `developerAppDesignPagesSaveDraft` |
| `POST` | `/v1/apps/{saasAppId}/design/pages/{pageKey}/validate` | `developerAppDesignPagesValidate` |
| `GET` | `/v1/apps/{saasAppId}/design/pages/{pageKey}/history` | `developerAppDesignPagesHistory` |
| `POST` | `/v1/apps/{saasAppId}/design/pages/{pageKey}/publish` | `developerAppDesignPagesPublish` |

**App design: authoring and app-wide custom fields**

| Method | Route | OpenAPI operationId |
| --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/design/authoring` | `developerAppDesignAuthoringGet` |
| `PUT` | `/v1/apps/{saasAppId}/design/authoring/user-types/{userTypeKey}` | `developerAppDesignAuthoringUpsertUserType` |
| `PUT` | `/v1/apps/{saasAppId}/design/authoring/user-types/{userTypeKey}/menu` | `developerAppDesignAuthoringSaveMenu` |
| `PUT` | `/v1/apps/{saasAppId}/design/authoring/user-types/{userTypeKey}/tenant-policy` | `developerAppDesignAuthoringSaveTenantPresentationPolicy` |
| `GET` | `/v1/apps/{saasAppId}/design/authoring/tenant-policies` | `developerAppDesignAuthoringGetTenantPresentationPolicies` |
| `GET` | `/v1/apps/{saasAppId}/design/fields/{moduleKey}` | `developerAppDesignFieldsList` |
| `POST` | `/v1/apps/{saasAppId}/design/fields/{moduleKey}` | `developerAppDesignFieldsCreate` |
| `PUT` | `/v1/apps/{saasAppId}/design/fields/{moduleKey}/{fieldDefinitionId}` | `developerAppDesignFieldsUpdate` |
| `GET` | `/v1/apps/{saasAppId}/design/fields/{moduleKey}/policy` | `developerAppDesignFieldsGetPolicy` |
| `PUT` | `/v1/apps/{saasAppId}/design/fields/{moduleKey}/policy` | `developerAppDesignFieldsSetPolicy` |

**App design: debug sessions (shared with the in-app debug drawer)**

| Method | Route | OpenAPI operationId |
| --- | --- | --- |
| `POST` | `/v1/apps/{saasAppId}/design/debug/sessions` | `developerAppDesignDebugStart` |
| `POST` | `/v1/apps/{saasAppId}/design/debug/sessions/{debugSessionId}/events` | `developerAppDesignDebugAppend` |
| `GET` | `/v1/apps/{saasAppId}/design/debug/sessions/{debugSessionId}` | `developerAppDesignDebugQuery` |
| `GET` | `/v1/apps/{saasAppId}/design/debug/sessions/history` | `developerAppDesignDebugHistory` |
| `GET` | `/v1/apps/{saasAppId}/design/debug/sessions/history/{debugSessionId}` | `developerAppDesignDebugHistoryTimeline` |
| `DELETE` | `/v1/apps/{saasAppId}/design/debug/sessions/{debugSessionId}` | `developerAppDesignDebugClose` |

**Payments and payment connectors**

| Method | Route | OpenAPI operationId |
| --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/payment-connectors` | `developerPaymentConnectorsList` |
| `POST` | `/v1/apps/{saasAppId}/payment-connectors` | `developerPaymentConnectorsCreate` |
| `PUT` | `/v1/apps/{saasAppId}/payment-connectors/{connectorId}` | `developerPaymentConnectorsUpdate` |
| `DELETE` | `/v1/apps/{saasAppId}/payment-connectors/{connectorId}` | `developerPaymentConnectorsDeactivate` |
| `GET` | `/v1/apps/{saasAppId}/modules/payments/settings` | `developerGetV1AppsModulesPaymentsSettings` |
| `PUT` | `/v1/apps/{saasAppId}/modules/payments/settings/{moduleKey}` | `developerPutV1AppsModulesPaymentsSettingsModuleKey` |
| `GET` | `/v1/apps/{saasAppId}/modules/payments/methods` | `developerGetV1AppsModulesPaymentsMethods` |
| `POST` | `/v1/apps/{saasAppId}/modules/payments/records/{recordId}/charges` | `developerPostV1AppsModulesPaymentsRecordsRecordIdGuidCharges` |

**Webhooks, deliveries and event types**

| Method | Route | OpenAPI operationId |
| --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/webhooks` | `developerWebhookSubscriptionsList` |
| `POST` | `/v1/apps/{saasAppId}/webhooks` | `developerWebhookSubscriptionsCreate` |
| `PUT` | `/v1/apps/{saasAppId}/webhooks/{subscriptionId}` | `developerWebhookSubscriptionsUpdate` |
| `POST` | `/v1/apps/{saasAppId}/webhooks/{subscriptionId}/rotate-secret` | `developerWebhookSubscriptionsRotate` |
| `GET` | `/v1/apps/{saasAppId}/webhook-deliveries` | `developerWebhookDeliveriesList` |
| `POST` | `/v1/apps/{saasAppId}/webhook-deliveries/{deliveryId}/retry` | `developerWebhookDeliveriesRetry` |
| `GET` | `/v1/apps/{saasAppId}/webhook-event-types` | `developerWebhookSubscriptionsListEventTypes` |

**Objects API**

| Method | Route | OpenAPI operationId |
| --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/objects` | `developerRecordsListObjects` |
| `GET` | `/v1/apps/{saasAppId}/objects/{objectKey}/schema` | `developerRecordsGetSchema` |
| `POST` | `/v1/apps/{saasAppId}/objects/{objectKey}/records/search` | `developerRecordsSearch` |
| `GET` | `/v1/apps/{saasAppId}/objects/{objectKey}/records/{recordId}` | `developerRecordsGet` |
| `PATCH` | `/v1/apps/{saasAppId}/objects/{objectKey}/records/{recordId}` | `developerRecordsUpdate` |
| `DELETE` | `/v1/apps/{saasAppId}/objects/{objectKey}/records/{recordId}` | `developerRecordsDelete` |
| `POST` | `/v1/apps/{saasAppId}/objects/{objectKey}/records` | `developerRecordsCreate` |
| `GET` | `/v1/apps/{saasAppId}/objects/{objectKey}/records/{recordId}/relationships` | `developerRecordsRelationships` |

**Custom-field definitions**

| Method | Route | OpenAPI operationId |
| --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/objects/{objectKey}/fields` | `developerCustomFieldsList` |
| `POST` | `/v1/apps/{saasAppId}/objects/{objectKey}/fields` | `developerCustomFieldsCreate` |
| `PUT` | `/v1/apps/{saasAppId}/objects/{objectKey}/fields/{fieldDefinitionId}` | `developerCustomFieldsUpdate` |

**Signup, tenant accounts, users and token exchange**

| Method | Route | OpenAPI operationId |
| --- | --- | --- |
| `POST` | `/v1/apps/{saasAppId}/accounts` | `developerHeadlessIdentityCreateAccount` |
| `GET` | `/v1/apps/{saasAppId}/accounts` | `developerOrganizationLifecycleList` |
| `GET` | `/v1/apps/{saasAppId}/accounts/by-external-id` | `developerHeadlessIdentityGetAccount` |
| `GET` | `/v1/apps/{saasAppId}/accounts/{appAccountId}/users` | `developerHeadlessIdentityListUsers` |
| `POST` | `/v1/apps/{saasAppId}/accounts/{appAccountId}/users` | `developerHeadlessIdentityCreateUser` |
| `PATCH` | `/v1/apps/{saasAppId}/accounts/{appAccountId}/users/{userId}` | `developerHeadlessIdentityUpdateUser` |
| `POST` | `/v1/apps/{saasAppId}/accounts/{appAccountId}/users/{userId}/deactivate` | `developerHeadlessIdentityDeactivateUser` |
| `POST` | `/v1/apps/{saasAppId}/user-token-exchanges` | `developerHeadlessIdentityExchangeUserToken` |

**Governed Skills and GoClaw assignment**

| Method | Route | OpenAPI operationId |
| --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/skills` | `developerSkillsList` |
| `GET` | `/v1/apps/{saasAppId}/skills/{skillVersionId}` | `developerSkillsGet` |
| `PUT` | `/v1/apps/{saasAppId}/goclaw-agents/{goClawAgentId}/skills/{skillKey}` | `developerSkillsAssign` |

**Tenant-owner outside forms**

| Method | Route | OpenAPI operationId |
| --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/outsideformsubmissions/endpoints` | `developerOutsideFormsList` |
| `POST` | `/v1/apps/{saasAppId}/outsideformsubmissions/endpoints` | `developerOutsideFormsCreate` |
| `PUT` | `/v1/apps/{saasAppId}/outsideformsubmissions/endpoints/{endpointId}` | `developerOutsideFormsUpdate` |
| `GET` | `/v1/apps/{saasAppId}/outsideformsubmissions/browser-challenge` | `developerOutsideFormsBrowserChallenge` |
| `GET` | `/v1/apps/{saasAppId}/outsideformsubmissions/{submissionId}` | `developerOutsideFormsGetSubmission` |

## Embed a page body or the whole published page

An external frontend can render either the portable page body inside its own navigation and theme or the complete BuildWithHQ page shell. Both choices use the published page definition and the same server-side entitlement fallback as the hosted tenant runtime; a page response grants no additional data authority.

| Method | Route | Result / purpose | Required credential | Required scope | OpenAPI operationId |
| --- | --- | --- | --- | --- | --- |
| `POST` | `/v1/apps/{saasAppId}/runtime/bindings` | Resolve 1..24 unique page binding keys with current-user record security | `DelegatedUserCredential` | `runtime.bindings.read` | `developerRuntimePagesResolveBindings` |
| `GET` | `/v1/apps/{saasAppId}/runtime/pages/{pageKey}` | Page body only (`components + page`); host supplies its own shell and navigation | `DelegatedUserCredential` | `runtime.pages.read` | `developerRuntimePagesGetBody` |
| `GET` | `/v1/apps/{saasAppId}/runtime/pages/{pageKey}/bootstrap` | Whole published page bootstrap (`shell + components + page`) | `DelegatedUserCredential` | `runtime.pages.read` | `developerRuntimePagesGetBootstrap` |

Use the body route for `components + page`. Its `includeDesignTokens` query parameter defaults to `false`, so the host's CSS wins; set it to `true` when page-level design tokens should travel with the body. Use the bootstrap route for `shell + components + page`, including BuildWithHQ menus, top bar, entitled-page navigation, and tenant presentation.

After loading either representation, send the page's unique binding keys to the batch binding route. Each item returns its own safe `ok`, `notFound`, `forbidden`, or `invalid` status. Resolution runs through the registered runtime binding contract and current secured stored procedures, so tenant, user, DataRole, location, and record visibility still come from the delegated identity rather than request data.

These routes accept only a delegated user token (`bwu_live_`); a live-app credential (`bwk_live_`) is rejected even if it names the scope. The Developer Kit SDK exposes the flow through `BuildWithHQRuntimeClient.getPageBody`, `getPageBootstrap`, and `resolveBindings`.

Installed marketplace services have a separate app-specific discovery and contract-projection surface. See [`MARKETPLACE-SERVICE-APIS.md`](../MARKETPLACE-SERVICE-APIS.md) for endpoint schemas, per-app OpenAPI, contract fingerprints, MCP discovery, and the shipped database-policy evidence.

## Manage SaaS CSS and design assets

A trusted backend can manage the theme and shared design library for its credential-bound SaaS application. These routes require a server-held live app credential (`bwk_live_`); draft and delegated-user credentials cannot use them.

| Method | Route | Purpose | Scope | OpenAPI operationId |
| --- | --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/assets` | List shared app-level assets | `assets.read` | `developerAssetsList` |
| `POST` | `/v1/apps/{saasAppId}/assets` | Multipart upload; 25 MiB maximum | `assets.write` | `developerAssetsUpload` |
| `DELETE` | `/v1/apps/{saasAppId}/assets/{assetId}` | Retire an asset and its stored bytes | `assets.write` | `developerAssetsDelete` |
| `GET` | `/v1/apps/{saasAppId}/assets/{assetId}/content` | Authenticated attachment download | `assets.read` | `developerAssetsContent` |
| `GET` | `/v1/apps/{saasAppId}/theme` | Read app theme, CSS variables, and design tokens | `themes.read` | `developerThemesGet` |
| `PUT` | `/v1/apps/{saasAppId}/theme` | Version-fenced app theme update | `themes.write` | `developerThemesPut` |

Theme updates use optimistic versioning and validated `--runtime-*` CSS variables plus bounded base design tokens. Asset upload is `multipart/form-data` with required binary `file` plus optional metadata. Uploads default to private; `isPublic=true` is required to receive an immutable `https://assets.buildwithhq.com/{saasAppId}/{assetId}` URL. Asset types are the fixed `document`, `font`, `image`, `stylesheet`, and `video` set. Compile Tailwind in the developer's own build pipeline and upload the resulting CSS; these routes never execute npm, plugins, arbitrary JavaScript, or build scripts. CSS is validated before publication; `.dll`, `.com`, and `.exe` are rejected. Page-specific structure and tokens remain on the draft/validate/publish routes. No route accepts a physical storage root, storage key, server, database, account, or connection string. See [`SAAS-DESIGN-ASSETS.md`](../SAAS-DESIGN-ASSETS.md) for the complete React, Tailwind, asset, and page-publishing workflow.

## Associate eligible records into a recursive graph

Every first-class or Build This entity backed by a canonical, authorized `Records.RecordId` can participate in the shared Record Graph. Derived projections that do not own a Record must link back to their native owner instead.

1. Open the seed record graph. The response returns the currently visible nodes and edges plus the registered `relationTypes` that may be selected; do not invent a relation key.

2. Add an edge from the seed to another authorized record using that target's `recordId` and one returned `relationKey`.

3. Repeat the same operation from any related record to build a multi-level graph. Traversal follows both incoming and outgoing edges, deduplicates previously visited nodes, and safely supports cyclic graphs.

4. Read the recursive result with `maxDepth` from 1 through 5 and `maxNodes` from 2 through 200. Smaller bounds are recommended for ordinary screens; the response reports `depthReached`, `nodeCount`, and `truncated`.

5. Remove an edge by its returned `recordRelationId`; removing a relationship does not delete either record.

| Surface | Purpose | Method and route | Body / bounds |
| --- | --- | --- | --- |
| Tenant runtime | Read recursive graph | `GET /api/modules/record-graph/{recordId}?maxDepth=2&maxNodes=100` | `maxDepth=1..5`; `maxNodes=2..200` |
| Tenant runtime | Add association | `PUT /api/modules/record-graph/{fromRecordId}/relations` | `{"toRecordId":"<target-guid>","relationKey":"<registered-key>"}` |
| Tenant runtime | Remove association | `DELETE /api/modules/record-graph/relations/{recordRelationId}` | No body |
| Developer API | Read recursive graph | `GET /v1/apps/{saasAppId}/modules/record-graph/{recordId}?maxDepth=2&maxNodes=100` | Same bounds |
| Developer API | Add association | `PUT /v1/apps/{saasAppId}/modules/record-graph/{fromRecordId}/relations` | `{"toRecordId":"<target-guid>","relationKey":"<registered-key>"}` |
| Developer API | Remove association | `DELETE /v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | No body |

Association security is symmetric: both endpoint records must be active, belong to the same routed tenant/SaaS, and be readable and editable inside the current user's DataRole, location, and direct-conversation participation envelope. Self-links, empty or unregistered relation keys, foreign/concealed records, and unauthorized edge removal are rejected safely. Repeating the same directed edge and relation type returns the existing relationship instead of creating a duplicate.

Record Graph is intentionally REST/SDK-only in this release. The curated 43-tool MCP surface does not expose these nine operations; an MCP client must call them through an approved REST/SDK integration rather than assuming a graph tool exists.

## Vendor generation provenance

The following are vendor-repository inputs, not regeneration instructions for a Developer Kit recipient. The ZIP intentionally omits internal catalogs, solution manifests, and the generator. Recipients can independently verify the two shipped contract inputs against their hashes below.

- Vendor `catalog-generator/catalog.json` — schema 2; internal source snapshot entries: tenant modules=304, additional server surfaces=115, unresolved module gaps=0. These are vendor input counts, not published API totals. SHA-256 `e92ab82896ae8d16d138487a66c8584234a459aeaa9babc7652ab36cb02ba6ad`.
- Shipped `openapi/buildwithhq-generated.json` — 422 published operations, SHA-256 `5f9bf4cee2ede9c6715ab4ec81822690e1c0cfd954571abb48f62d624e9527f2`.
- Shipped `products/build-this-api-recipes.json` — 18 recipes and 73 referenced recipe operations, SHA-256 `93a48843a6bb577a2a300739428b35a88c74df8566b923439a4a9eb998f38bcb`.
- Vendor `solutions/build-this/*/solution.json` — explicit production-solution operation and composition contracts.
- Vendor regeneration command: `python tools/generate_api_route_inventory.py`; vendor verification command: `python tools/generate_api_route_inventory.py --check`.

## 1. First-class modules

[]()

**Connected work (`connected-work`)**

API bases: `/api/modules/record-graph`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `5`; Developer `5` |
| Add / create / execute | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Edit / update / modify | Tenant `3`; Developer `3` |
| Delete / remove / deactivate | Tenant `2`; Developer `2` |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | Tenant `10`; Developer `10` |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (10):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `DELETE` | `/api/modules/record-graph/knowledge-relations/{recordRelationId:guid}` | Relationship graph | `UnlinkKnowledgeAsync` |
| `GET` | `/api/modules/record-graph/records` | Relationship graph | `SearchAsync` |
| `DELETE` | `/api/modules/record-graph/relations/{recordRelationId:guid}` | Associate / remove relationship | `RemoveRelationAsync` |
| `GET` | `/api/modules/record-graph/{recordId:guid}` | Relationship graph | `GetAsync` |
| `PUT` | `/api/modules/record-graph/{recordId:guid}/favorite` | Favorite / unfavorite | `SetFavoriteAsync` |
| `GET` | `/api/modules/record-graph/{recordId:guid}/knowledge` | Relationship graph | `RelatedKnowledgeAsync` |
| `PUT` | `/api/modules/record-graph/{recordId:guid}/knowledge` | Associate / add | `LinkKnowledgeAsync` |
| `GET` | `/api/modules/record-graph/{recordId:guid}/knowledge/candidates` | Relationship graph | `ContextualKnowledgeAsync` |
| `GET` | `/api/modules/record-graph/{recordId:guid}/relations` | List / view | `ListRelatedAsync` |
| `PUT` | `/api/modules/record-graph/{recordId:guid}/relations` | Associate / add | `AddRelationAsync` |

Developer API routes (10):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/knowledge-relations/{recordRelationId}` | Relationship graph | `developerDeleteV1AppsModulesRecordGraphKnowledgeRelationsRecordRelationIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/records` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecords` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesRecordGraphRecordIdGuidFavorite` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/knowledge` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuidKnowledge` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/knowledge` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidKnowledge` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/knowledge/candidates` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuidKnowledgeCandidates` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | List / view | `developerGetV1AppsModulesRecordGraphRecordIdGuidRelations` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` |

[]()

**Knowledge finder (`knowledge-finder`)**

API bases: `/api/modules/knowledge-core`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `14`; Developer `14` |
| Add / create / execute | Tenant `17`; Developer `17` |
| Edit / update / modify | Tenant `3`; Developer `3` |
| Delete / remove / deactivate | Tenant `2`; Developer `2` |
| Favorite / unfavorite | No direct route; use [Favorites](#first-class-favorites)  only for supported authorized Records |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (36):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/knowledge-core` | List | `ListAsync` |
| `POST` | `/api/modules/knowledge-core` | Create | `CreateAsync` |
| `GET` | `/api/modules/knowledge-core/assignment-lookup` | List / view | `AssignmentLookupAsync` |
| `GET` | `/api/modules/knowledge-core/collections` | Collections | `CollectionsAsync` |
| `POST` | `/api/modules/knowledge-core/collections` | Create Collection | `CreateCollectionAsync` |
| `PUT` | `/api/modules/knowledge-core/collections/{collectionId:guid}` | Update Collection | `UpdateCollectionAsync` |
| `DELETE` | `/api/modules/knowledge-core/collections/{collectionId:guid}/items/{recordId:guid}` | Remove Collection Item | `RemoveCollectionItemAsync` |
| `POST` | `/api/modules/knowledge-core/collections/{collectionId:guid}/items/{recordId:guid}` | Add Collection Item | `AddCollectionItemAsync` |
| `GET` | `/api/modules/knowledge-core/gaps` | Gaps | `GapsAsync` |
| `GET` | `/api/modules/knowledge-core/health` | Health | `HealthAsync` |
| `DELETE` | `/api/modules/knowledge-core/owners/{knowledgeOwnerId:guid}` | Remove Owner | `RemoveOwnerAsync` |
| `GET` | `/api/modules/knowledge-core/questions` | Questions | `QuestionsAsync` |
| `POST` | `/api/modules/knowledge-core/questions` | Create Question | `CreateQuestionAsync` |
| `PUT` | `/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}` | Edit Question | `EditQuestionAsync` |
| `POST` | `/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/answer` | Answer Question | `AnswerQuestionAsync` |
| `POST` | `/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/assign` | Assign Question | `AssignQuestionAsync` |
| `POST` | `/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/close` | Close Question | `CloseQuestionAsync` |
| `POST` | `/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/convert` | Convert Question | `ConvertQuestionAsync` |
| `GET` | `/api/modules/knowledge-core/reviews` | Reviews | `ReviewsAsync` |
| `POST` | `/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/begin` | Begin Review | `BeginReviewAsync` |
| `POST` | `/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/complete` | Complete Review | `CompleteReviewAsync` |
| `POST` | `/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/reassign` | Reassign Review | `ReassignReviewAsync` |
| `GET` | `/api/modules/knowledge-core/support-learning/candidates` | Support Learning Candidates | `SupportLearningCandidatesAsync` |
| `POST` | `/api/modules/knowledge-core/support-learning/candidates` | Create Support Learning Candidate | `CreateSupportLearningCandidateAsync` |
| `GET` | `/api/modules/knowledge-core/unowned` | Unowned | `UnownedAsync` |
| `GET` | `/api/modules/knowledge-core/{recordId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/modules/knowledge-core/{recordId:guid}` | Update | `UpdateAsync` |
| `POST` | `/api/modules/knowledge-core/{recordId:guid}/archive` | Archive | `ArchiveAsync` |
| `GET` | `/api/modules/knowledge-core/{recordId:guid}/feedback` | Feedback Summary | `FeedbackSummaryAsync` |
| `POST` | `/api/modules/knowledge-core/{recordId:guid}/feedback` | Record Feedback | `RecordFeedbackAsync` |
| `GET` | `/api/modules/knowledge-core/{recordId:guid}/feedback/comments` | Feedback Comments | `FeedbackCommentsAsync` |
| `GET` | `/api/modules/knowledge-core/{recordId:guid}/owners` | Owners | `OwnersAsync` |
| `POST` | `/api/modules/knowledge-core/{recordId:guid}/owners` | Set Owner | `SetOwnerAsync` |
| `POST` | `/api/modules/knowledge-core/{recordId:guid}/publish` | Publish | `PublishAsync` |
| `POST` | `/api/modules/knowledge-core/{recordId:guid}/restore` | Restore | `RestoreAsync` |
| `GET` | `/api/modules/knowledge-core/{recordId:guid}/revisions` | Revisions | `RevisionsAsync` |

Developer API routes (36):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core` | List / view | `developerGetV1AppsModulesKnowledgeCore` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCore` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/assignment-lookup` | List / view | `developerGetV1AppsModulesKnowledgeCoreAssignmentLookup` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/collections` | List / view | `developerGetV1AppsModulesKnowledgeCoreCollections` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/collections` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreCollections` |
| `PUT` | `/v1/apps/{saasAppId}/modules/knowledge-core/collections/{collectionId}` | Edit / update / modify | `developerPutV1AppsModulesKnowledgeCoreCollectionsCollectionIdGuid` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/knowledge-core/collections/{collectionId}/items/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesKnowledgeCoreCollectionsCollectionIdGuidItemsRecordIdGuid` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/collections/{collectionId}/items/{recordId}` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreCollectionsCollectionIdGuidItemsRecordIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/gaps` | List / view | `developerGetV1AppsModulesKnowledgeCoreGaps` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/health` | List / view | `developerGetV1AppsModulesKnowledgeCoreHealth` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/knowledge-core/owners/{knowledgeOwnerId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesKnowledgeCoreOwnersKnowledgeOwnerIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/questions` | List / view | `developerGetV1AppsModulesKnowledgeCoreQuestions` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/questions` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreQuestions` |
| `PUT` | `/v1/apps/{saasAppId}/modules/knowledge-core/questions/{knowledgeQuestionId}` | Edit / update / modify | `developerPutV1AppsModulesKnowledgeCoreQuestionsKnowledgeQuestionIdGuid` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/questions/{knowledgeQuestionId}/answer` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreQuestionsKnowledgeQuestionIdGuidAnswer` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/questions/{knowledgeQuestionId}/assign` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreQuestionsKnowledgeQuestionIdGuidAssign` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/questions/{knowledgeQuestionId}/close` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreQuestionsKnowledgeQuestionIdGuidClose` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/questions/{knowledgeQuestionId}/convert` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreQuestionsKnowledgeQuestionIdGuidConvert` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/reviews` | List / view | `developerGetV1AppsModulesKnowledgeCoreReviews` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/reviews/{reviewCycleId}/begin` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreReviewsReviewCycleIdGuidBegin` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/reviews/{reviewCycleId}/complete` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreReviewsReviewCycleIdGuidComplete` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/reviews/{reviewCycleId}/reassign` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreReviewsReviewCycleIdGuidReassign` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/support-learning/candidates` | List / view | `developerGetV1AppsModulesKnowledgeCoreSupportLearningCandidates` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/support-learning/candidates` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreSupportLearningCandidates` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/unowned` | List / view | `developerGetV1AppsModulesKnowledgeCoreUnowned` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}` | List / view | `developerGetV1AppsModulesKnowledgeCoreRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesKnowledgeCoreRecordIdGuid` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/archive` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreRecordIdGuidArchive` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/feedback` | List / view | `developerGetV1AppsModulesKnowledgeCoreRecordIdGuidFeedback` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/feedback` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreRecordIdGuidFeedback` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/feedback/comments` | List / view | `developerGetV1AppsModulesKnowledgeCoreRecordIdGuidFeedbackComments` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/owners` | List / view | `developerGetV1AppsModulesKnowledgeCoreRecordIdGuidOwners` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/owners` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreRecordIdGuidOwners` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/publish` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreRecordIdGuidPublish` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/restore` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreRecordIdGuidRestore` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/revisions` | List / view | `developerGetV1AppsModulesKnowledgeCoreRecordIdGuidRevisions` |

[]()

**Universal Inbox (`universal-inbox`)**

API bases: `/api/inbox`, `/api/inbox/items`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `13`; Developer `13` |
| Add / create / execute | Tenant `5`; Developer `4` |
| Edit / update / modify | Tenant `4`; Developer `4` |
| Delete / remove / deactivate | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Favorite / unfavorite | No direct route; use [Favorites](#first-class-favorites)  only for supported authorized Records |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (22):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/inbox/badge` | Get Badge | `GetBadgeAsync` |
| `GET` | `/api/inbox/badge/indicator` | Get Badge Indicator | `GetBadgeIndicatorAsync` |
| `GET` | `/api/inbox/channels/ticketing` | Mailbox ticketing configuration | `GetChannelTicketingAsync` |
| `PUT` | `/api/inbox/channels/{channelConnectionId:guid}/ticketing` | Mailbox ticketing configuration | `SetChannelTicketingAsync` |
| `GET` | `/api/inbox/delivery/debug` | Get Delivery Debug | `GetDeliveryDebugAsync` |
| `POST` | `/api/inbox/delivery/{outboundMessageId:guid}/retry` | Retry operation | `RetryDeliveryAsync` |
| `GET` | `/api/inbox/email-channels/ticketing` | Mailbox ticketing configuration | `GetEmailTicketingAsync` |
| `PUT` | `/api/inbox/email-channels/{channelConnectionId:guid}/ticketing` | Mailbox ticketing configuration | `SetEmailTicketingAsync` |
| `GET` | `/api/inbox/items` | Get Items | `GetItemsAsync` |
| `GET` | `/api/inbox/items/{inboxItemId:guid}` | Get Item | `GetItemAsync` |
| `PUT` | `/api/inbox/items/{inboxItemId:guid}/human-state` | Human state / resolution | `UpdateHumanStateAsync` |
| `POST` | `/api/inbox/items/{inboxItemId:guid}/reply` | Message / reply | `ReplyAsync` |
| `POST` | `/api/inbox/items/{inboxItemId:guid}/workflow-approval` | Workflow approval | `DecideAsync` |
| `GET` | `/api/inbox/lego-catalog` | Lego Catalog | `LegoCatalogAsync` |
| `GET` | `/api/inbox/lego-presentation` | Lego Presentation | `LegoPresentationAsync` |
| `GET` | `/api/inbox/notifications` | Get Notifications | `GetNotificationsAsync` |
| `GET` | `/api/inbox/support-lanes` | List | `ListAsync` |
| `POST` | `/api/inbox/support-lanes` | Create | `CreateAsync` |
| `GET` | `/api/inbox/support-lanes/options` | Options | `OptionsAsync` |
| `GET` | `/api/inbox/support-lanes/{laneId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/inbox/support-lanes/{laneId:guid}` | Update | `UpdateAsync` |
| `POST` | `/api/inbox/support-lanes/{laneId:guid}/retire` | Retire | `RetireAsync` |

Developer API routes (21):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/inbox/badge` | List / view | `developerGetV1AppsInboxBadge` |
| `GET` | `/v1/apps/{saasAppId}/inbox/badge/indicator` | List / view | `developerGetV1AppsInboxBadgeIndicator` |
| `GET` | `/v1/apps/{saasAppId}/inbox/channels/ticketing` | Mailbox ticketing configuration | `developerGetV1AppsInboxChannelsTicketing` |
| `PUT` | `/v1/apps/{saasAppId}/inbox/channels/{channelConnectionId}/ticketing` | Mailbox ticketing configuration | `developerPutV1AppsInboxChannelsChannelConnectionIdGuidTicketing` |
| `GET` | `/v1/apps/{saasAppId}/inbox/delivery/debug` | List / view | `developerGetV1AppsInboxDeliveryDebug` |
| `POST` | `/v1/apps/{saasAppId}/inbox/delivery/{outboundMessageId}/retry` | Retry operation | `developerPostV1AppsInboxDeliveryOutboundMessageIdGuidRetry` |
| `GET` | `/v1/apps/{saasAppId}/inbox/email-channels/ticketing` | Mailbox ticketing configuration | `developerGetV1AppsInboxEmailChannelsTicketing` |
| `PUT` | `/v1/apps/{saasAppId}/inbox/email-channels/{channelConnectionId}/ticketing` | Mailbox ticketing configuration | `developerPutV1AppsInboxEmailChannelsChannelConnectionIdGuidTicketing` |
| `GET` | `/v1/apps/{saasAppId}/inbox/items` | List / view | `developerGetV1AppsInboxItems` |
| `GET` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}` | List / view | `developerGetV1AppsInboxItemsInboxItemIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}/human-state` | Human state / resolution | `developerPutV1AppsInboxItemsInboxItemIdGuidHumanState` |
| `POST` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}/reply` | Message / reply | `developerPostV1AppsInboxItemsInboxItemIdGuidReply` |
| `GET` | `/v1/apps/{saasAppId}/inbox/lego-catalog` | List / view | `developerGetV1AppsInboxLegoCatalog` |
| `GET` | `/v1/apps/{saasAppId}/inbox/lego-presentation` | List / view | `developerGetV1AppsInboxLegoPresentation` |
| `GET` | `/v1/apps/{saasAppId}/inbox/notifications` | List / view | `developerGetV1AppsInboxNotifications` |
| `GET` | `/v1/apps/{saasAppId}/inbox/support-lanes` | List / view | `developerGetV1AppsInboxSupportLanes` |
| `POST` | `/v1/apps/{saasAppId}/inbox/support-lanes` | Add / create / execute | `developerPostV1AppsInboxSupportLanes` |
| `GET` | `/v1/apps/{saasAppId}/inbox/support-lanes/options` | List / view | `developerGetV1AppsInboxSupportLanesOptions` |
| `GET` | `/v1/apps/{saasAppId}/inbox/support-lanes/{laneId}` | List / view | `developerGetV1AppsInboxSupportLanesLaneIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/inbox/support-lanes/{laneId}` | Edit / update / modify | `developerPutV1AppsInboxSupportLanesLaneIdGuid` |
| `POST` | `/v1/apps/{saasAppId}/inbox/support-lanes/{laneId}/retire` | Add / create / execute | `developerPostV1AppsInboxSupportLanesLaneIdGuidRetire` |

[]()

**Checklists & Signoffs (`checklists-signoffs`)**

API bases: `/api/modules/checklists-signoffs`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `8`; Developer `8` |
| Add / create / execute | Tenant `5`; Developer `5` |
| Edit / update / modify | Tenant `2`; Developer `2` |
| Delete / remove / deactivate | Tenant `2`; Developer `2` |
| Favorite / unfavorite | No direct route; use [Favorites](#first-class-favorites)  only for supported authorized Records |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | Tenant `2`; Developer `2` |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (17):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/checklists-signoffs/export` | Export | `ExportAsync` |
| `GET` | `/api/modules/checklists-signoffs/export/capability` | Get Export Capability | `GetExportCapabilityAsync` |
| `PUT` | `/api/modules/checklists-signoffs/items/{checklistRunItemId:guid}` | Update Item | `UpdateItemAsync` |
| `POST` | `/api/modules/checklists-signoffs/items/{checklistRunItemId:guid}/proof` | File proof / evidence | `AttachProofAsync` |
| `GET` | `/api/modules/checklists-signoffs/lego/catalog` | Get Lego Catalog | `GetLegoCatalog` |
| `GET` | `/api/modules/checklists-signoffs/lookups/{lookupId:guid}` | Get Lego Lookup | `GetLegoLookupAsync` |
| `DELETE` | `/api/modules/checklists-signoffs/proof/{checklistItemEvidenceId:guid}` | File proof / evidence | `RemoveProofAsync` |
| `GET` | `/api/modules/checklists-signoffs/runs` | List Runs | `ListRunsAsync` |
| `POST` | `/api/modules/checklists-signoffs/runs` | Start Run | `StartRunAsync` |
| `GET` | `/api/modules/checklists-signoffs/runs/{checklistRunId:guid}` | Get Run | `GetRunAsync` |
| `POST` | `/api/modules/checklists-signoffs/runs/{checklistRunId:guid}/cancel` | Cancel Run | `CancelRunAsync` |
| `POST` | `/api/modules/checklists-signoffs/runs/{checklistRunId:guid}/submit` | Submit workflow | `SubmitAsync` |
| `GET` | `/api/modules/checklists-signoffs/templates` | List Templates | `ListTemplatesAsync` |
| `POST` | `/api/modules/checklists-signoffs/templates` | Create Template | `CreateTemplateAsync` |
| `DELETE` | `/api/modules/checklists-signoffs/templates/{checklistTemplateId:guid}` | Remove Template | `RemoveTemplateAsync` |
| `GET` | `/api/modules/checklists-signoffs/templates/{checklistTemplateId:guid}` | Get Template | `GetTemplateAsync` |
| `PUT` | `/api/modules/checklists-signoffs/templates/{checklistTemplateId:guid}` | Update Template | `UpdateTemplateAsync` |

Developer API routes (17):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/export` | List / view | `developerGetV1AppsModulesChecklistsSignoffsExport` |
| `GET` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/export/capability` | List / view | `developerGetV1AppsModulesChecklistsSignoffsExportCapability` |
| `PUT` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/items/{checklistRunItemId}` | Edit / update / modify | `developerPutV1AppsModulesChecklistsSignoffsItemsChecklistRunItemIdGuid` |
| `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/items/{checklistRunItemId}/proof` | File proof / evidence | `developerPostV1AppsModulesChecklistsSignoffsItemsChecklistRunItemIdGuidProof` |
| `GET` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/lego/catalog` | List / view | `developerGetV1AppsModulesChecklistsSignoffsLegoCatalog` |
| `GET` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/lookups/{lookupId}` | List / view | `developerGetV1AppsModulesChecklistsSignoffsLookupsLookupIdGuid` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/proof/{checklistItemEvidenceId}` | File proof / evidence | `developerDeleteV1AppsModulesChecklistsSignoffsProofChecklistItemEvidenceIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs` | List / view | `developerGetV1AppsModulesChecklistsSignoffsRuns` |
| `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs` | Add / create / execute | `developerPostV1AppsModulesChecklistsSignoffsRuns` |
| `GET` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs/{checklistRunId}` | List / view | `developerGetV1AppsModulesChecklistsSignoffsRunsChecklistRunIdGuid` |
| `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs/{checklistRunId}/cancel` | Add / create / execute | `developerPostV1AppsModulesChecklistsSignoffsRunsChecklistRunIdGuidCancel` |
| `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs/{checklistRunId}/submit` | Submit workflow | `developerPostV1AppsModulesChecklistsSignoffsRunsChecklistRunIdGuidSubmit` |
| `GET` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates` | List / view | `developerGetV1AppsModulesChecklistsSignoffsTemplates` |
| `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates` | Add / create / execute | `developerPostV1AppsModulesChecklistsSignoffsTemplates` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates/{checklistTemplateId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesChecklistsSignoffsTemplatesChecklistTemplateIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates/{checklistTemplateId}` | List / view | `developerGetV1AppsModulesChecklistsSignoffsTemplatesChecklistTemplateIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates/{checklistTemplateId}` | Edit / update / modify | `developerPutV1AppsModulesChecklistsSignoffsTemplatesChecklistTemplateIdGuid` |

[]()

**GoClaw (`goclaw`)**

API bases: `/api/goclaw/agents`, `/api/goclaw/approvals`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `3`; Developer `3` |
| Add / create / execute | Tenant `4`; Developer `4` |
| Edit / update / modify | Tenant `1`; Developer `0` |
| Delete / remove / deactivate | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Favorite / unfavorite | No direct route; use [Favorites](#first-class-favorites)  only for supported authorized Records |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (8):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `PUT` | `/api/goclaw/agents/{goClawAgentId:guid}/authority` | Configure | `ConfigureAsync` |
| `GET` | `/api/goclaw/approvals` | Get | `GetAsync` |
| `GET` | `/api/goclaw/approvals/lego/catalog` | Lego Catalog | `LegoCatalog` |
| `GET` | `/api/goclaw/approvals/lego/presentation` | Presentation metadata | `LegoPresentationAsync` |
| `POST` | `/api/goclaw/approvals/{suggestionBatchId:guid}/approve` | Approve | `ApproveAsync` |
| `POST` | `/api/goclaw/approvals/{suggestionBatchId:guid}/reject` | Reject | `RejectAsync` |
| `POST` | `/api/goclaw/approvals/{suggestionBatchId:guid}/retry` | Retry operation | `RetryAsync` |
| `POST` | `/api/goclaw/approvals/{suggestionBatchId:guid}/take-over` | Take Over | `TakeOverAsync` |

Developer API routes (7):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/goclaw/approvals` | List / view | `developerGetV1AppsGoclawApprovals` |
| `GET` | `/v1/apps/{saasAppId}/goclaw/approvals/lego/catalog` | List / view | `developerGetV1AppsGoclawApprovalsLegoCatalog` |
| `GET` | `/v1/apps/{saasAppId}/goclaw/approvals/lego/presentation` | Presentation metadata | `developerGetV1AppsGoclawApprovalsLegoPresentation` |
| `POST` | `/v1/apps/{saasAppId}/goclaw/approvals/{suggestionBatchId}/approve` | Approve | `developerPostV1AppsGoclawApprovalsSuggestionBatchIdGuidApprove` |
| `POST` | `/v1/apps/{saasAppId}/goclaw/approvals/{suggestionBatchId}/reject` | Reject | `developerPostV1AppsGoclawApprovalsSuggestionBatchIdGuidReject` |
| `POST` | `/v1/apps/{saasAppId}/goclaw/approvals/{suggestionBatchId}/retry` | Retry operation | `developerPostV1AppsGoclawApprovalsSuggestionBatchIdGuidRetry` |
| `POST` | `/v1/apps/{saasAppId}/goclaw/approvals/{suggestionBatchId}/take-over` | Add / create / execute | `developerPostV1AppsGoclawApprovalsSuggestionBatchIdGuidTakeOver` |

[]()

**AI Insights (`ai-insights`)**

API bases: `/api/modules/ai-insights`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `3`; Developer `2` |
| Add / create / execute | Tenant `1`; Developer `0` |
| Edit / update / modify | Tenant `4`; Developer `1` |
| Delete / remove / deactivate | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Favorite / unfavorite | No direct route; use [Favorites](#first-class-favorites)  only for supported authorized Records |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (8):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/ai-insights` | List | `ListAsync` |
| `GET` | `/api/modules/ai-insights/settings` | Get Settings | `GetSettingsAsync` |
| `PUT` | `/api/modules/ai-insights/settings` | Save Settings | `SaveSettingsAsync` |
| `POST` | `/api/modules/ai-insights/settings/directives` | Add Directive | `AddDirectiveAsync` |
| `PUT` | `/api/modules/ai-insights/settings/directives/{directiveId:guid}` | Save Directive | `SaveDirectiveAsync` |
| `PUT` | `/api/modules/ai-insights/settings/starters/{directiveId:guid}` | Set Starter Directive | `SetStarterDirectiveAsync` |
| `GET` | `/api/modules/ai-insights/{insightId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/modules/ai-insights/{insightId:guid}/state` | State transition | `SetStateAsync` |

Developer API routes (3):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/ai-insights` | List / view | `developerGetV1AppsModulesAiInsights` |
| `GET` | `/v1/apps/{saasAppId}/modules/ai-insights/{insightId}` | List / view | `developerGetV1AppsModulesAiInsightsInsightIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/ai-insights/{insightId}/state` | State transition | `developerPutV1AppsModulesAiInsightsInsightIdGuidState` |

[]()

**Contacts (`contacts`)**

API bases: `/api/modules/contacts`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `9`; Developer `8` |
| Add / create / execute | Tenant `2`; Developer `1` |
| Edit / update / modify | Tenant `4`; Developer `2` |
| Delete / remove / deactivate | Tenant `1`; Developer `1` |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (16):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/contacts` | List | `ListAsync` |
| `POST` | `/api/modules/contacts` | Create | `CreateAsync` |
| `GET` | `/api/modules/contacts/count` | Count | `CountAsync` |
| `GET` | `/api/modules/contacts/create-visibility-options` | List / view | `GetCreateVisibilityOptionsAsync` |
| `GET` | `/api/modules/contacts/export` | Export | `ExportAsync` |
| `GET` | `/api/modules/contacts/export/capability` | Get Export Capability | `GetExportCapabilityAsync` |
| `GET` | `/api/modules/contacts/list-preferences` | Get List Preferences | `GetListPreferencesAsync` |
| `PUT` | `/api/modules/contacts/list-preferences/{scope}` | Save List Preferences | `SaveListPreferencesAsync` |
| `GET` | `/api/modules/contacts/lookups/{lookupId:guid}` | Get Lookup | `GetLookupAsync` |
| `GET` | `/api/modules/contacts/schema` | Schema / field metadata | `GetSchemaAsync` |
| `DELETE` | `/api/modules/contacts/{recordId:guid}` | Remove | `RemoveAsync` |
| `GET` | `/api/modules/contacts/{recordId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/modules/contacts/{recordId:guid}` | Update | `UpdateAsync` |
| `PUT` | `/api/modules/contacts/{recordId:guid}/favorite` | Favorite / unfavorite | `FavoriteAsync` |
| `PUT` | `/api/modules/contacts/{recordId:guid}/secure-fields/{fieldDefinitionId:guid}` | Set Secure Field | `SetSecureFieldAsync` |
| `POST` | `/api/modules/contacts/{recordId:guid}/secure-fields/{fieldDefinitionId:guid}/reveal` | Reveal Secure Field | `RevealSecureFieldAsync` |

Developer API routes (12):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/contacts` | List / view | `developerGetV1AppsModulesContacts` |
| `POST` | `/v1/apps/{saasAppId}/modules/contacts` | Add / create / execute | `developerPostV1AppsModulesContacts` |
| `GET` | `/v1/apps/{saasAppId}/modules/contacts/count` | List / view | `developerGetV1AppsModulesContactsCount` |
| `GET` | `/v1/apps/{saasAppId}/modules/contacts/create-visibility-options` | List / view | `developerGetV1AppsModulesContactsCreateVisibilityOptions` |
| `GET` | `/v1/apps/{saasAppId}/modules/contacts/export` | List / view | `developerGetV1AppsModulesContactsExport` |
| `GET` | `/v1/apps/{saasAppId}/modules/contacts/export/capability` | List / view | `developerGetV1AppsModulesContactsExportCapability` |
| `GET` | `/v1/apps/{saasAppId}/modules/contacts/lookups/{lookupId}` | List / view | `developerGetV1AppsModulesContactsLookupsLookupIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/contacts/schema` | Schema / field metadata | `developerGetV1AppsModulesContactsSchema` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/contacts/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesContactsRecordIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/contacts/{recordId}` | List / view | `developerGetV1AppsModulesContactsRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/contacts/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesContactsRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/contacts/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesContactsRecordIdGuidFavorite` |

[]()

**Work Orders (`work-orders`)**

API bases: `/api/modules/work-orders`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `7`; Developer `8` |
| Add / create / execute | Tenant `1`; Developer `1` |
| Edit / update / modify | Tenant `3`; Developer `3` |
| Delete / remove / deactivate | Tenant `1`; Developer `1` |
| Favorite / unfavorite | No direct route; use [Favorites](#first-class-favorites)  only for supported authorized Records |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (12):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/work-orders` | List | `ListAsync` |
| `POST` | `/api/modules/work-orders` | Create | `CreateAsync` |
| `GET` | `/api/modules/work-orders/export` | Export | `ExportAsync` |
| `GET` | `/api/modules/work-orders/export/capability` | Get Export Capability | `GetExportCapabilityAsync` |
| `GET` | `/api/modules/work-orders/lookups/{lookupId:guid}` | Get Lookup | `GetLookupAsync` |
| `GET` | `/api/modules/work-orders/schema` | Schema / field metadata | `GetSchemaAsync` |
| `DELETE` | `/api/modules/work-orders/{recordId:guid}` | Remove | `RemoveAsync` |
| `GET` | `/api/modules/work-orders/{recordId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/modules/work-orders/{recordId:guid}` | Update | `UpdateAsync` |
| `PUT` | `/api/modules/work-orders/{recordId:guid}/assignment` | Assignment update | `AssignAsync` |
| `PUT` | `/api/modules/work-orders/{recordId:guid}/status` | Status transition | `StatusAsync` |
| `GET` | `/api/modules/work-orders/{recordId:guid}/status-transitions` | List / view | `GetStatusTransitionsAsync` |

Developer API routes (13):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/work-orders` | List / view | `developerGetV1AppsModulesWorkOrders` |
| `POST` | `/v1/apps/{saasAppId}/modules/work-orders` | Add / create / execute | `developerPostV1AppsModulesWorkOrders` |
| `GET` | `/v1/apps/{saasAppId}/modules/work-orders/export` | List / view | `developerGetV1AppsModulesWorkOrdersExport` |
| `GET` | `/v1/apps/{saasAppId}/modules/work-orders/export/capability` | List / view | `developerGetV1AppsModulesWorkOrdersExportCapability` |
| `GET` | `/v1/apps/{saasAppId}/modules/work-orders/lookups/{lookupId}` | List / view | `developerGetV1AppsModulesWorkOrdersLookupsLookupIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/work-orders/presentation` | Presentation metadata | `developerPresentationsGet` |
| `GET` | `/v1/apps/{saasAppId}/modules/work-orders/schema` | Schema / field metadata | `developerGetV1AppsModulesWorkOrdersSchema` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/work-orders/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesWorkOrdersRecordIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/work-orders/{recordId}` | List / view | `developerGetV1AppsModulesWorkOrdersRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/work-orders/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesWorkOrdersRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/work-orders/{recordId}/assignment` | Assignment update | `developerPutV1AppsModulesWorkOrdersRecordIdGuidAssignment` |
| `PUT` | `/v1/apps/{saasAppId}/modules/work-orders/{recordId}/status` | Status transition | `developerPutV1AppsModulesWorkOrdersRecordIdGuidStatus` |
| `GET` | `/v1/apps/{saasAppId}/modules/work-orders/{recordId}/status-transitions` | List / view | `developerGetV1AppsModulesWorkOrdersRecordIdGuidStatusTransitions` |

[]()

**Reservations (`reservations`)**

API bases: `/api/modules/reservations`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `8`; Developer `8` |
| Add / create / execute | Tenant `2`; Developer `2` |
| Edit / update / modify | Tenant `4`; Developer `4` |
| Delete / remove / deactivate | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Favorite / unfavorite | No direct route; use [Favorites](#first-class-favorites)  only for supported authorized Records |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (14):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/reservations` | List | `ListAsync` |
| `GET` | `/api/modules/reservations/assignees` | List / view | `GetAssigneesAsync` |
| `GET` | `/api/modules/reservations/capabilities` | Capabilities | `CapabilitiesAsync` |
| `GET` | `/api/modules/reservations/export` | Export | `ExportAsync` |
| `GET` | `/api/modules/reservations/export/capability` | Get Export Capability | `GetExportCapabilityAsync` |
| `GET` | `/api/modules/reservations/lego/catalog` | Lego Catalog | `LegoCatalog` |
| `GET` | `/api/modules/reservations/products` | List Products | `ListProductsAsync` |
| `POST` | `/api/modules/reservations/products` | Upsert Product | `UpsertProductAsync` |
| `POST` | `/api/modules/reservations/purchase` | Purchase | `PurchaseAsync` |
| `GET` | `/api/modules/reservations/{recordId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/modules/reservations/{recordId:guid}/custom-fields` | Update Custom Fields | `UpdateCustomFieldsAsync` |
| `PUT` | `/api/modules/reservations/{recordId:guid}/followups` | Update Followup | `UpdateFollowupAsync` |
| `PUT` | `/api/modules/reservations/{recordId:guid}/schedule` | Reschedule | `RescheduleAsync` |
| `PUT` | `/api/modules/reservations/{recordId:guid}/status` | Status transition | `SetStatusAsync` |

Developer API routes (14):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/reservations` | List / view | `developerGetV1AppsModulesReservations` |
| `GET` | `/v1/apps/{saasAppId}/modules/reservations/assignees` | List / view | `developerGetV1AppsModulesReservationsAssignees` |
| `GET` | `/v1/apps/{saasAppId}/modules/reservations/capabilities` | List / view | `developerGetV1AppsModulesReservationsCapabilities` |
| `GET` | `/v1/apps/{saasAppId}/modules/reservations/export` | List / view | `developerGetV1AppsModulesReservationsExport` |
| `GET` | `/v1/apps/{saasAppId}/modules/reservations/export/capability` | List / view | `developerGetV1AppsModulesReservationsExportCapability` |
| `GET` | `/v1/apps/{saasAppId}/modules/reservations/lego/catalog` | List / view | `developerGetV1AppsModulesReservationsLegoCatalog` |
| `GET` | `/v1/apps/{saasAppId}/modules/reservations/products` | List / view | `developerGetV1AppsModulesReservationsProducts` |
| `POST` | `/v1/apps/{saasAppId}/modules/reservations/products` | Add / create / execute | `developerPostV1AppsModulesReservationsProducts` |
| `POST` | `/v1/apps/{saasAppId}/modules/reservations/purchase` | Add / create / execute | `developerPostV1AppsModulesReservationsPurchase` |
| `GET` | `/v1/apps/{saasAppId}/modules/reservations/{recordId}` | List / view | `developerGetV1AppsModulesReservationsRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/reservations/{recordId}/custom-fields` | Edit / update / modify | `developerPutV1AppsModulesReservationsRecordIdGuidCustomFields` |
| `PUT` | `/v1/apps/{saasAppId}/modules/reservations/{recordId}/followups` | Edit / update / modify | `developerPutV1AppsModulesReservationsRecordIdGuidFollowups` |
| `PUT` | `/v1/apps/{saasAppId}/modules/reservations/{recordId}/schedule` | Edit / update / modify | `developerPutV1AppsModulesReservationsRecordIdGuidSchedule` |
| `PUT` | `/v1/apps/{saasAppId}/modules/reservations/{recordId}/status` | Status transition | `developerPutV1AppsModulesReservationsRecordIdGuidStatus` |

[]()

**Calendar (`calendar`)**

API bases: `/api/modules/calendar`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `4`; Developer `4` |
| Add / create / execute | Tenant `1`; Developer `1` |
| Edit / update / modify | Tenant `2`; Developer `2` |
| Delete / remove / deactivate | Tenant `1`; Developer `1` |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (8):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/calendar` | List | `ListAsync` |
| `POST` | `/api/modules/calendar` | Create | `CreateAsync` |
| `GET` | `/api/modules/calendar/capabilities` | Capabilities | `CapabilitiesAsync` |
| `GET` | `/api/modules/calendar/lego/catalog` | Lego Catalog | `LegoCatalog` |
| `DELETE` | `/api/modules/calendar/{recordId:guid}` | Remove | `RemoveAsync` |
| `GET` | `/api/modules/calendar/{recordId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/modules/calendar/{recordId:guid}` | Update | `UpdateAsync` |
| `PUT` | `/api/modules/calendar/{recordId:guid}/favorite` | Favorite / unfavorite | `FavoriteAsync` |

Developer API routes (8):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/calendar` | List / view | `developerGetV1AppsModulesCalendar` |
| `POST` | `/v1/apps/{saasAppId}/modules/calendar` | Add / create / execute | `developerPostV1AppsModulesCalendar` |
| `GET` | `/v1/apps/{saasAppId}/modules/calendar/capabilities` | List / view | `developerGetV1AppsModulesCalendarCapabilities` |
| `GET` | `/v1/apps/{saasAppId}/modules/calendar/lego/catalog` | List / view | `developerGetV1AppsModulesCalendarLegoCatalog` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/calendar/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesCalendarRecordIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/calendar/{recordId}` | List / view | `developerGetV1AppsModulesCalendarRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/calendar/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesCalendarRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/calendar/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesCalendarRecordIdGuidFavorite` |

[]()

**Files (`files`)**

API bases: `/api/modules/files`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `9`; Developer `8` |
| Add / create / execute | Tenant `4`; Developer `4` |
| Edit / update / modify | Tenant `3`; Developer `2` |
| Delete / remove / deactivate | Tenant `3`; Developer `3` |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | Tenant `19`; Developer `17` |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (19):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/files` | File / attachment | `ListAsync` |
| `GET` | `/api/modules/files/capabilities` | File / attachment | `CapabilitiesAsync` |
| `GET` | `/api/modules/files/lego/catalog` | File / attachment | `LegoCatalog` |
| `GET` | `/api/modules/files/personal-limit` | File / attachment | `GetPersonalLimitAsync` |
| `PUT` | `/api/modules/files/personal-limit` | File / attachment | `SavePersonalLimitAsync` |
| `POST` | `/api/modules/files/upload` | File / attachment | `UploadAsync` |
| `DELETE` | `/api/modules/files/{recordId:guid}` | File / attachment | `RemoveAsync` |
| `GET` | `/api/modules/files/{recordId:guid}` | File / attachment | `GetAsync` |
| `PUT` | `/api/modules/files/{recordId:guid}` | File / attachment | `UpdateAsync` |
| `POST` | `/api/modules/files/{recordId:guid}/attachments` | File / attachment | `AttachAsync` |
| `DELETE` | `/api/modules/files/{recordId:guid}/attachments/{attachmentId:guid}` | File / attachment | `DetachAsync` |
| `GET` | `/api/modules/files/{recordId:guid}/comments` | File / attachment | `ListCommentsAsync` |
| `POST` | `/api/modules/files/{recordId:guid}/comments` | File / attachment | `AddCommentAsync` |
| `DELETE` | `/api/modules/files/{recordId:guid}/comments/{commentId:guid}` | File / attachment | `RemoveCommentAsync` |
| `GET` | `/api/modules/files/{recordId:guid}/content` | File / attachment | `DownloadAsync` |
| `PUT` | `/api/modules/files/{recordId:guid}/favorite` | Favorite / unfavorite | `FavoriteAsync` |
| `GET` | `/api/modules/files/{recordId:guid}/versions` | File / attachment | `ListVersionsAsync` |
| `POST` | `/api/modules/files/{recordId:guid}/versions` | File / attachment | `UploadVersionAsync` |
| `GET` | `/api/modules/files/{recordId:guid}/versions/{version:int}/content` | File / attachment | `DownloadVersionAsync` |

Developer API routes (17):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/files` | File / attachment | `developerGetV1AppsModulesFiles` |
| `GET` | `/v1/apps/{saasAppId}/modules/files/capabilities` | File / attachment | `developerGetV1AppsModulesFilesCapabilities` |
| `GET` | `/v1/apps/{saasAppId}/modules/files/lego/catalog` | File / attachment | `developerGetV1AppsModulesFilesLegoCatalog` |
| `POST` | `/v1/apps/{saasAppId}/modules/files/upload` | File / attachment | `developerPostV1AppsModulesFilesUpload` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/files/{recordId}` | File / attachment | `developerDeleteV1AppsModulesFilesRecordIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/files/{recordId}` | File / attachment | `developerGetV1AppsModulesFilesRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/files/{recordId}` | File / attachment | `developerPutV1AppsModulesFilesRecordIdGuid` |
| `POST` | `/v1/apps/{saasAppId}/modules/files/{recordId}/attachments` | File / attachment | `developerPostV1AppsModulesFilesRecordIdGuidAttachments` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/files/{recordId}/attachments/{attachmentId}` | File / attachment | `developerDeleteV1AppsModulesFilesRecordIdGuidAttachmentsAttachmentIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/files/{recordId}/comments` | File / attachment | `developerGetV1AppsModulesFilesRecordIdGuidComments` |
| `POST` | `/v1/apps/{saasAppId}/modules/files/{recordId}/comments` | File / attachment | `developerPostV1AppsModulesFilesRecordIdGuidComments` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/files/{recordId}/comments/{commentId}` | File / attachment | `developerDeleteV1AppsModulesFilesRecordIdGuidCommentsCommentIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/files/{recordId}/content` | File / attachment | `developerGetV1AppsModulesFilesRecordIdGuidContent` |
| `PUT` | `/v1/apps/{saasAppId}/modules/files/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesFilesRecordIdGuidFavorite` |
| `GET` | `/v1/apps/{saasAppId}/modules/files/{recordId}/versions` | File / attachment | `developerGetV1AppsModulesFilesRecordIdGuidVersions` |
| `POST` | `/v1/apps/{saasAppId}/modules/files/{recordId}/versions` | File / attachment | `developerPostV1AppsModulesFilesRecordIdGuidVersions` |
| `GET` | `/v1/apps/{saasAppId}/modules/files/{recordId}/versions/{version}/content` | File / attachment | `developerGetV1AppsModulesFilesRecordIdGuidVersionsVersionIntContent` |

[]()

**Conversations (`conversations`)**

API bases: `/api/modules/conversations`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `7`; Developer `7` |
| Add / create / execute | Tenant `3`; Developer `3` |
| Edit / update / modify | Tenant `2`; Developer `2` |
| Delete / remove / deactivate | Tenant `1`; Developer `1` |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | Tenant `1`; Developer `1` |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (13):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/conversations` | List | `ListAsync` |
| `POST` | `/api/modules/conversations` | Create | `CreateAsync` |
| `GET` | `/api/modules/conversations/capabilities` | Capabilities | `CapabilitiesAsync` |
| `POST` | `/api/modules/conversations/direct` | Send Direct | `SendDirectAsync` |
| `GET` | `/api/modules/conversations/direct/scope` | Direct Scope | `DirectScopeAsync` |
| `GET` | `/api/modules/conversations/lego-catalog` | Lego Catalog | `LegoCatalogAsync` |
| `GET` | `/api/modules/conversations/lego-presentation` | Lego Presentation | `LegoPresentationAsync` |
| `DELETE` | `/api/modules/conversations/{recordId:guid}` | Remove | `RemoveAsync` |
| `GET` | `/api/modules/conversations/{recordId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/modules/conversations/{recordId:guid}` | Update | `UpdateAsync` |
| `PUT` | `/api/modules/conversations/{recordId:guid}/favorite` | Favorite / unfavorite | `FavoriteAsync` |
| `POST` | `/api/modules/conversations/{recordId:guid}/messages` | Message / reply | `ReplyAsync` |
| `GET` | `/api/modules/conversations/{recordId:guid}/messages/{messageId:guid}/attachments/{fileId:guid}/content` | Message / reply | `DownloadAttachmentAsync` |

Developer API routes (13):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/conversations` | List / view | `developerGetV1AppsModulesConversations` |
| `POST` | `/v1/apps/{saasAppId}/modules/conversations` | Add / create / execute | `developerPostV1AppsModulesConversations` |
| `GET` | `/v1/apps/{saasAppId}/modules/conversations/capabilities` | List / view | `developerGetV1AppsModulesConversationsCapabilities` |
| `POST` | `/v1/apps/{saasAppId}/modules/conversations/direct` | Add / create / execute | `developerPostV1AppsModulesConversationsDirect` |
| `GET` | `/v1/apps/{saasAppId}/modules/conversations/direct/scope` | List / view | `developerGetV1AppsModulesConversationsDirectScope` |
| `GET` | `/v1/apps/{saasAppId}/modules/conversations/lego-catalog` | List / view | `developerGetV1AppsModulesConversationsLegoCatalog` |
| `GET` | `/v1/apps/{saasAppId}/modules/conversations/lego-presentation` | List / view | `developerGetV1AppsModulesConversationsLegoPresentation` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/conversations/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesConversationsRecordIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/conversations/{recordId}` | List / view | `developerGetV1AppsModulesConversationsRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/conversations/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesConversationsRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/conversations/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesConversationsRecordIdGuidFavorite` |
| `POST` | `/v1/apps/{saasAppId}/modules/conversations/{recordId}/messages` | Message / reply | `developerPostV1AppsModulesConversationsRecordIdGuidMessages` |
| `GET` | `/v1/apps/{saasAppId}/modules/conversations/{recordId}/messages/{messageId}/attachments/{fileId}/content` | Message / reply | `developerGetV1AppsModulesConversationsRecordIdGuidMessagesMessageIdGuidAttachmentsFileIdGuidContent` |

[]()

**Company news (`company-news`)**

API bases: `/api/modules/company-news`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `4`; Developer `4` |
| Add / create / execute | Tenant `1`; Developer `1` |
| Edit / update / modify | Tenant `3`; Developer `3` |
| Delete / remove / deactivate | Tenant `1`; Developer `1` |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (9):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/company-news` | List | `ListAsync` |
| `POST` | `/api/modules/company-news` | Create | `CreateAsync` |
| `GET` | `/api/modules/company-news/lookups/{lookupId:guid}` | Lookup | `LookupAsync` |
| `GET` | `/api/modules/company-news/schema` | Schema / field metadata | `SchemaAsync` |
| `DELETE` | `/api/modules/company-news/{recordId:guid}` | Remove | `RemoveAsync` |
| `GET` | `/api/modules/company-news/{recordId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/modules/company-news/{recordId:guid}` | Update | `UpdateAsync` |
| `PUT` | `/api/modules/company-news/{recordId:guid}/favorite` | Favorite / unfavorite | `FavoriteAsync` |
| `PUT` | `/api/modules/company-news/{recordId:guid}/published` | Published | `PublishedAsync` |

Developer API routes (9):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/company-news` | List / view | `developerGetV1AppsModulesCompanyNews` |
| `POST` | `/v1/apps/{saasAppId}/modules/company-news` | Add / create / execute | `developerPostV1AppsModulesCompanyNews` |
| `GET` | `/v1/apps/{saasAppId}/modules/company-news/lookups/{lookupId}` | List / view | `developerGetV1AppsModulesCompanyNewsLookupsLookupIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/company-news/schema` | Schema / field metadata | `developerGetV1AppsModulesCompanyNewsSchema` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/company-news/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesCompanyNewsRecordIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/company-news/{recordId}` | List / view | `developerGetV1AppsModulesCompanyNewsRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/company-news/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesCompanyNewsRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/company-news/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesCompanyNewsRecordIdGuidFavorite` |
| `PUT` | `/v1/apps/{saasAppId}/modules/company-news/{recordId}/published` | Edit / update / modify | `developerPutV1AppsModulesCompanyNewsRecordIdGuidPublished` |

[]()

**Knowledge Core (`knowledge-core`)**

API bases: `/api/modules/knowledge-articles`, `/api/modules/knowledge-core`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `17`; Developer `17` |
| Add / create / execute | Tenant `18`; Developer `18` |
| Edit / update / modify | Tenant `5`; Developer `5` |
| Delete / remove / deactivate | Tenant `3`; Developer `3` |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (43):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/knowledge-articles` | List | `ListAsync` |
| `POST` | `/api/modules/knowledge-articles` | Create | `CreateAsync` |
| `GET` | `/api/modules/knowledge-articles/lego/catalog` | Lego Catalog | `LegoCatalog` |
| `DELETE` | `/api/modules/knowledge-articles/{recordId:guid}` | Remove | `RemoveAsync` |
| `GET` | `/api/modules/knowledge-articles/{recordId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/modules/knowledge-articles/{recordId:guid}` | Update | `UpdateAsync` |
| `PUT` | `/api/modules/knowledge-articles/{recordId:guid}/favorite` | Favorite / unfavorite | `FavoriteAsync` |
| `GET` | `/api/modules/knowledge-core` | List | `ListAsync` |
| `POST` | `/api/modules/knowledge-core` | Create | `CreateAsync` |
| `GET` | `/api/modules/knowledge-core/assignment-lookup` | List / view | `AssignmentLookupAsync` |
| `GET` | `/api/modules/knowledge-core/collections` | Collections | `CollectionsAsync` |
| `POST` | `/api/modules/knowledge-core/collections` | Create Collection | `CreateCollectionAsync` |
| `PUT` | `/api/modules/knowledge-core/collections/{collectionId:guid}` | Update Collection | `UpdateCollectionAsync` |
| `DELETE` | `/api/modules/knowledge-core/collections/{collectionId:guid}/items/{recordId:guid}` | Remove Collection Item | `RemoveCollectionItemAsync` |
| `POST` | `/api/modules/knowledge-core/collections/{collectionId:guid}/items/{recordId:guid}` | Add Collection Item | `AddCollectionItemAsync` |
| `GET` | `/api/modules/knowledge-core/gaps` | Gaps | `GapsAsync` |
| `GET` | `/api/modules/knowledge-core/health` | Health | `HealthAsync` |
| `DELETE` | `/api/modules/knowledge-core/owners/{knowledgeOwnerId:guid}` | Remove Owner | `RemoveOwnerAsync` |
| `GET` | `/api/modules/knowledge-core/questions` | Questions | `QuestionsAsync` |
| `POST` | `/api/modules/knowledge-core/questions` | Create Question | `CreateQuestionAsync` |
| `PUT` | `/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}` | Edit Question | `EditQuestionAsync` |
| `POST` | `/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/answer` | Answer Question | `AnswerQuestionAsync` |
| `POST` | `/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/assign` | Assign Question | `AssignQuestionAsync` |
| `POST` | `/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/close` | Close Question | `CloseQuestionAsync` |
| `POST` | `/api/modules/knowledge-core/questions/{knowledgeQuestionId:guid}/convert` | Convert Question | `ConvertQuestionAsync` |
| `GET` | `/api/modules/knowledge-core/reviews` | Reviews | `ReviewsAsync` |
| `POST` | `/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/begin` | Begin Review | `BeginReviewAsync` |
| `POST` | `/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/complete` | Complete Review | `CompleteReviewAsync` |
| `POST` | `/api/modules/knowledge-core/reviews/{reviewCycleId:guid}/reassign` | Reassign Review | `ReassignReviewAsync` |
| `GET` | `/api/modules/knowledge-core/support-learning/candidates` | Support Learning Candidates | `SupportLearningCandidatesAsync` |
| `POST` | `/api/modules/knowledge-core/support-learning/candidates` | Create Support Learning Candidate | `CreateSupportLearningCandidateAsync` |
| `GET` | `/api/modules/knowledge-core/unowned` | Unowned | `UnownedAsync` |
| `GET` | `/api/modules/knowledge-core/{recordId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/modules/knowledge-core/{recordId:guid}` | Update | `UpdateAsync` |
| `POST` | `/api/modules/knowledge-core/{recordId:guid}/archive` | Archive | `ArchiveAsync` |
| `GET` | `/api/modules/knowledge-core/{recordId:guid}/feedback` | Feedback Summary | `FeedbackSummaryAsync` |
| `POST` | `/api/modules/knowledge-core/{recordId:guid}/feedback` | Record Feedback | `RecordFeedbackAsync` |
| `GET` | `/api/modules/knowledge-core/{recordId:guid}/feedback/comments` | Feedback Comments | `FeedbackCommentsAsync` |
| `GET` | `/api/modules/knowledge-core/{recordId:guid}/owners` | Owners | `OwnersAsync` |
| `POST` | `/api/modules/knowledge-core/{recordId:guid}/owners` | Set Owner | `SetOwnerAsync` |
| `POST` | `/api/modules/knowledge-core/{recordId:guid}/publish` | Publish | `PublishAsync` |
| `POST` | `/api/modules/knowledge-core/{recordId:guid}/restore` | Restore | `RestoreAsync` |
| `GET` | `/api/modules/knowledge-core/{recordId:guid}/revisions` | Revisions | `RevisionsAsync` |

Developer API routes (43):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-articles` | List / view | `developerGetV1AppsModulesKnowledgeArticles` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-articles` | Add / create / execute | `developerPostV1AppsModulesKnowledgeArticles` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-articles/lego/catalog` | List / view | `developerGetV1AppsModulesKnowledgeArticlesLegoCatalog` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/knowledge-articles/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesKnowledgeArticlesRecordIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-articles/{recordId}` | List / view | `developerGetV1AppsModulesKnowledgeArticlesRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/knowledge-articles/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesKnowledgeArticlesRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/knowledge-articles/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesKnowledgeArticlesRecordIdGuidFavorite` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core` | List / view | `developerGetV1AppsModulesKnowledgeCore` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCore` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/assignment-lookup` | List / view | `developerGetV1AppsModulesKnowledgeCoreAssignmentLookup` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/collections` | List / view | `developerGetV1AppsModulesKnowledgeCoreCollections` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/collections` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreCollections` |
| `PUT` | `/v1/apps/{saasAppId}/modules/knowledge-core/collections/{collectionId}` | Edit / update / modify | `developerPutV1AppsModulesKnowledgeCoreCollectionsCollectionIdGuid` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/knowledge-core/collections/{collectionId}/items/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesKnowledgeCoreCollectionsCollectionIdGuidItemsRecordIdGuid` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/collections/{collectionId}/items/{recordId}` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreCollectionsCollectionIdGuidItemsRecordIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/gaps` | List / view | `developerGetV1AppsModulesKnowledgeCoreGaps` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/health` | List / view | `developerGetV1AppsModulesKnowledgeCoreHealth` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/knowledge-core/owners/{knowledgeOwnerId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesKnowledgeCoreOwnersKnowledgeOwnerIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/questions` | List / view | `developerGetV1AppsModulesKnowledgeCoreQuestions` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/questions` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreQuestions` |
| `PUT` | `/v1/apps/{saasAppId}/modules/knowledge-core/questions/{knowledgeQuestionId}` | Edit / update / modify | `developerPutV1AppsModulesKnowledgeCoreQuestionsKnowledgeQuestionIdGuid` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/questions/{knowledgeQuestionId}/answer` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreQuestionsKnowledgeQuestionIdGuidAnswer` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/questions/{knowledgeQuestionId}/assign` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreQuestionsKnowledgeQuestionIdGuidAssign` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/questions/{knowledgeQuestionId}/close` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreQuestionsKnowledgeQuestionIdGuidClose` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/questions/{knowledgeQuestionId}/convert` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreQuestionsKnowledgeQuestionIdGuidConvert` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/reviews` | List / view | `developerGetV1AppsModulesKnowledgeCoreReviews` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/reviews/{reviewCycleId}/begin` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreReviewsReviewCycleIdGuidBegin` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/reviews/{reviewCycleId}/complete` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreReviewsReviewCycleIdGuidComplete` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/reviews/{reviewCycleId}/reassign` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreReviewsReviewCycleIdGuidReassign` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/support-learning/candidates` | List / view | `developerGetV1AppsModulesKnowledgeCoreSupportLearningCandidates` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/support-learning/candidates` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreSupportLearningCandidates` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/unowned` | List / view | `developerGetV1AppsModulesKnowledgeCoreUnowned` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}` | List / view | `developerGetV1AppsModulesKnowledgeCoreRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesKnowledgeCoreRecordIdGuid` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/archive` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreRecordIdGuidArchive` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/feedback` | List / view | `developerGetV1AppsModulesKnowledgeCoreRecordIdGuidFeedback` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/feedback` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreRecordIdGuidFeedback` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/feedback/comments` | List / view | `developerGetV1AppsModulesKnowledgeCoreRecordIdGuidFeedbackComments` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/owners` | List / view | `developerGetV1AppsModulesKnowledgeCoreRecordIdGuidOwners` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/owners` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreRecordIdGuidOwners` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/publish` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreRecordIdGuidPublish` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/restore` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreRecordIdGuidRestore` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/revisions` | List / view | `developerGetV1AppsModulesKnowledgeCoreRecordIdGuidRevisions` |

[]()

**Web links (`web-links`)**

API bases: `/api/modules/web-links`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `4`; Developer `4` |
| Add / create / execute | Tenant `1`; Developer `1` |
| Edit / update / modify | Tenant `2`; Developer `2` |
| Delete / remove / deactivate | Tenant `1`; Developer `1` |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (8):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/web-links` | List | `ListAsync` |
| `POST` | `/api/modules/web-links` | Create | `CreateAsync` |
| `GET` | `/api/modules/web-links/lego/catalog` | Get Lego Catalog | `GetLegoCatalog` |
| `GET` | `/api/modules/web-links/lookups/{lookupId:guid}` | Get Lego Lookup | `GetLegoLookupAsync` |
| `DELETE` | `/api/modules/web-links/{recordId:guid}` | Remove | `RemoveAsync` |
| `GET` | `/api/modules/web-links/{recordId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/modules/web-links/{recordId:guid}` | Update | `UpdateAsync` |
| `PUT` | `/api/modules/web-links/{recordId:guid}/favorite` | Favorite / unfavorite | `FavoriteAsync` |

Developer API routes (8):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/web-links` | List / view | `developerGetV1AppsModulesWebLinks` |
| `POST` | `/v1/apps/{saasAppId}/modules/web-links` | Add / create / execute | `developerPostV1AppsModulesWebLinks` |
| `GET` | `/v1/apps/{saasAppId}/modules/web-links/lego/catalog` | List / view | `developerGetV1AppsModulesWebLinksLegoCatalog` |
| `GET` | `/v1/apps/{saasAppId}/modules/web-links/lookups/{lookupId}` | List / view | `developerGetV1AppsModulesWebLinksLookupsLookupIdGuid` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/web-links/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesWebLinksRecordIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/web-links/{recordId}` | List / view | `developerGetV1AppsModulesWebLinksRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/web-links/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesWebLinksRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/web-links/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesWebLinksRecordIdGuidFavorite` |

[]()

**Chat rooms (`chat-rooms`)**

API bases: `/api/modules/chat-rooms`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `4`; Developer `4` |
| Add / create / execute | Tenant `2`; Developer `2` |
| Edit / update / modify | Tenant `6`; Developer `6` |
| Delete / remove / deactivate | Tenant `2`; Developer `2` |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (14):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/chat-rooms` | List | `ListAsync` |
| `POST` | `/api/modules/chat-rooms` | Create | `CreateAsync` |
| `GET` | `/api/modules/chat-rooms/lego/catalog` | Lego Catalog | `LegoCatalogAsync` |
| `DELETE` | `/api/modules/chat-rooms/{recordId:guid}` | Remove | `RemoveAsync` |
| `GET` | `/api/modules/chat-rooms/{recordId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/modules/chat-rooms/{recordId:guid}` | Update | `UpdateAsync` |
| `PUT` | `/api/modules/chat-rooms/{recordId:guid}/favorite` | Favorite / unfavorite | `FavoriteAsync` |
| `GET` | `/api/modules/chat-rooms/{recordId:guid}/members/lookup` | List / view | `MemberLookupAsync` |
| `PUT` | `/api/modules/chat-rooms/{recordId:guid}/members/{memberUserId:guid}` | Member management | `MemberAsync` |
| `POST` | `/api/modules/chat-rooms/{recordId:guid}/messages` | Message / reply | `PostMessageAsync` |
| `DELETE` | `/api/modules/chat-rooms/{recordId:guid}/messages/{chatMessageId:guid}` | Message / reply | `RemoveMessageAsync` |
| `PUT` | `/api/modules/chat-rooms/{recordId:guid}/messages/{chatMessageId:guid}` | Message / reply | `UpdateMessageAsync` |
| `PUT` | `/api/modules/chat-rooms/{recordId:guid}/messages/{chatMessageId:guid}/reaction` | Message / reply | `ReactionAsync` |
| `PUT` | `/api/modules/chat-rooms/{recordId:guid}/read` | Mark Read | `MarkReadAsync` |

Developer API routes (14):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/chat-rooms` | List / view | `developerGetV1AppsModulesChatRooms` |
| `POST` | `/v1/apps/{saasAppId}/modules/chat-rooms` | Add / create / execute | `developerPostV1AppsModulesChatRooms` |
| `GET` | `/v1/apps/{saasAppId}/modules/chat-rooms/lego/catalog` | List / view | `developerGetV1AppsModulesChatRoomsLegoCatalog` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/chat-rooms/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesChatRoomsRecordIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/chat-rooms/{recordId}` | List / view | `developerGetV1AppsModulesChatRoomsRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/chat-rooms/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesChatRoomsRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/chat-rooms/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesChatRoomsRecordIdGuidFavorite` |
| `GET` | `/v1/apps/{saasAppId}/modules/chat-rooms/{recordId}/members/lookup` | List / view | `developerGetV1AppsModulesChatRoomsRecordIdGuidMembersLookup` |
| `PUT` | `/v1/apps/{saasAppId}/modules/chat-rooms/{recordId}/members/{memberUserId}` | Member management | `developerPutV1AppsModulesChatRoomsRecordIdGuidMembersMemberUserIdGuid` |
| `POST` | `/v1/apps/{saasAppId}/modules/chat-rooms/{recordId}/messages` | Message / reply | `developerPostV1AppsModulesChatRoomsRecordIdGuidMessages` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/chat-rooms/{recordId}/messages/{chatMessageId}` | Message / reply | `developerDeleteV1AppsModulesChatRoomsRecordIdGuidMessagesChatMessageIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/chat-rooms/{recordId}/messages/{chatMessageId}` | Message / reply | `developerPutV1AppsModulesChatRoomsRecordIdGuidMessagesChatMessageIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/chat-rooms/{recordId}/messages/{chatMessageId}/reaction` | Message / reply | `developerPutV1AppsModulesChatRoomsRecordIdGuidMessagesChatMessageIdGuidReaction` |
| `PUT` | `/v1/apps/{saasAppId}/modules/chat-rooms/{recordId}/read` | Edit / update / modify | `developerPutV1AppsModulesChatRoomsRecordIdGuidRead` |

[]()

**Discussion Boards (`discussion-boards`)**

API bases: `/api/modules/discussion-boards`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `4`; Developer `4` |
| Add / create / execute | Tenant `3`; Developer `3` |
| Edit / update / modify | Tenant `4`; Developer `4` |
| Delete / remove / deactivate | Tenant `3`; Developer `3` |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (14):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/discussion-boards` | List | `ListAsync` |
| `POST` | `/api/modules/discussion-boards` | Create Board | `CreateBoardAsync` |
| `GET` | `/api/modules/discussion-boards/lego/catalog` | Lego Catalog | `LegoCatalogAsync` |
| `DELETE` | `/api/modules/discussion-boards/posts/{recordId:guid}` | Remove Post | `RemovePostAsync` |
| `PUT` | `/api/modules/discussion-boards/posts/{recordId:guid}` | Update Post | `UpdatePostAsync` |
| `PUT` | `/api/modules/discussion-boards/records/{recordId:guid}/favorite` | Favorite / unfavorite | `SetFavoriteAsync` |
| `DELETE` | `/api/modules/discussion-boards/topics/{recordId:guid}` | Remove Topic | `RemoveTopicAsync` |
| `GET` | `/api/modules/discussion-boards/topics/{recordId:guid}` | Get Topic | `GetTopicAsync` |
| `PUT` | `/api/modules/discussion-boards/topics/{recordId:guid}` | Update Topic | `UpdateTopicAsync` |
| `POST` | `/api/modules/discussion-boards/topics/{topicRecordId:guid}/posts` | Post Reply | `PostReplyAsync` |
| `POST` | `/api/modules/discussion-boards/{boardRecordId:guid}/topics` | Create Topic | `CreateTopicAsync` |
| `DELETE` | `/api/modules/discussion-boards/{recordId:guid}` | Remove Board | `RemoveBoardAsync` |
| `GET` | `/api/modules/discussion-boards/{recordId:guid}` | Get Board | `GetBoardAsync` |
| `PUT` | `/api/modules/discussion-boards/{recordId:guid}` | Update Board | `UpdateBoardAsync` |

Developer API routes (14):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/discussion-boards` | List / view | `developerGetV1AppsModulesDiscussionBoards` |
| `POST` | `/v1/apps/{saasAppId}/modules/discussion-boards` | Add / create / execute | `developerPostV1AppsModulesDiscussionBoards` |
| `GET` | `/v1/apps/{saasAppId}/modules/discussion-boards/lego/catalog` | List / view | `developerGetV1AppsModulesDiscussionBoardsLegoCatalog` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/discussion-boards/posts/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDiscussionBoardsPostsRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/discussion-boards/posts/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDiscussionBoardsPostsRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/discussion-boards/records/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDiscussionBoardsRecordsRecordIdGuidFavorite` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/discussion-boards/topics/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDiscussionBoardsTopicsRecordIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/discussion-boards/topics/{recordId}` | List / view | `developerGetV1AppsModulesDiscussionBoardsTopicsRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/discussion-boards/topics/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDiscussionBoardsTopicsRecordIdGuid` |
| `POST` | `/v1/apps/{saasAppId}/modules/discussion-boards/topics/{topicRecordId}/posts` | Add / create / execute | `developerPostV1AppsModulesDiscussionBoardsTopicsTopicRecordIdGuidPosts` |
| `POST` | `/v1/apps/{saasAppId}/modules/discussion-boards/{boardRecordId}/topics` | Add / create / execute | `developerPostV1AppsModulesDiscussionBoardsBoardRecordIdGuidTopics` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/discussion-boards/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDiscussionBoardsRecordIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/discussion-boards/{recordId}` | List / view | `developerGetV1AppsModulesDiscussionBoardsRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/discussion-boards/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDiscussionBoardsRecordIdGuid` |

[]()

**Mail reader (`mail-reader`)**

API bases: `/api/modules/mail-reader`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `3`; Developer `2` |
| Add / create / execute | Tenant `3`; Developer `0` |
| Edit / update / modify | Tenant `4`; Developer `2` |
| Delete / remove / deactivate | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (10):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/mail-reader` | List | `ListAsync` |
| `GET` | `/api/modules/mail-reader/mailboxes` | List Mailboxes | `ListMailboxesAsync` |
| `POST` | `/api/modules/mail-reader/mailboxes` | Create Mailbox | `CreateMailboxAsync` |
| `PUT` | `/api/modules/mail-reader/mailboxes/{mailboxId:guid}` | Update Mailbox | `UpdateMailboxAsync` |
| `POST` | `/api/modules/mail-reader/mailboxes/{mailboxRecordId:guid}/compose` | Compose | `ComposeAsync` |
| `PUT` | `/api/modules/mail-reader/mailboxes/{mailboxRecordId:guid}/credentials/{purpose}` | Set Mailbox Credential | `SetMailboxCredentialAsync` |
| `GET` | `/api/modules/mail-reader/{recordId:guid}` | Get | `GetAsync` |
| `POST` | `/api/modules/mail-reader/{recordId:guid}/archive` | Archive | `ArchiveAsync` |
| `PUT` | `/api/modules/mail-reader/{recordId:guid}/favorite` | Favorite / unfavorite | `SetFavoriteAsync` |
| `PUT` | `/api/modules/mail-reader/{recordId:guid}/read` | Set Read | `SetReadAsync` |

Developer API routes (4):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/mail-reader` | List / view | `developerGetV1AppsModulesMailReader` |
| `GET` | `/v1/apps/{saasAppId}/modules/mail-reader/{recordId}` | List / view | `developerGetV1AppsModulesMailReaderRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/mail-reader/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesMailReaderRecordIdGuidFavorite` |
| `PUT` | `/v1/apps/{saasAppId}/modules/mail-reader/{recordId}/read` | Edit / update / modify | `developerPutV1AppsModulesMailReaderRecordIdGuidRead` |

[]()

**Favorites (`favorites`)**

API bases: `/api/modules/favorites`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `5`; Developer `5` |
| Add / create / execute | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Edit / update / modify | Tenant `2`; Developer `2` |
| Delete / remove / deactivate | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Favorite / unfavorite | Tenant `7`; Developer `7` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (7):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/favorites` | Favorite / unfavorite | `ListAsync` |
| `GET` | `/api/modules/favorites/presentation` | Favorite / unfavorite | `PresentationAsync` |
| `GET` | `/api/modules/favorites/schema` | Favorite / unfavorite | `SchemaAsync` |
| `GET` | `/api/modules/favorites/{recordId:guid}` | Favorite / unfavorite | `GetAsync` |
| `PUT` | `/api/modules/favorites/{recordId:guid}/favorite` | Favorite / unfavorite | `SetAsync` |
| `PUT` | `/api/modules/favorites/{recordId:guid}/preferences` | Favorite / unfavorite | `UpdateAsync` |
| `GET` | `/api/modules/favorites/{recordId:guid}/state` | Favorite / unfavorite | `GetStateAsync` |

Developer API routes (7):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/favorites` | Favorite / unfavorite | `developerGetV1AppsModulesFavorites` |
| `GET` | `/v1/apps/{saasAppId}/modules/favorites/presentation` | Favorite / unfavorite | `developerGetV1AppsModulesFavoritesPresentation` |
| `GET` | `/v1/apps/{saasAppId}/modules/favorites/schema` | Favorite / unfavorite | `developerGetV1AppsModulesFavoritesSchema` |
| `GET` | `/v1/apps/{saasAppId}/modules/favorites/{recordId}` | Favorite / unfavorite | `developerGetV1AppsModulesFavoritesRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/favorites/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesFavoritesRecordIdGuidFavorite` |
| `PUT` | `/v1/apps/{saasAppId}/modules/favorites/{recordId}/preferences` | Favorite / unfavorite | `developerPutV1AppsModulesFavoritesRecordIdGuidPreferences` |
| `GET` | `/v1/apps/{saasAppId}/modules/favorites/{recordId}/state` | Favorite / unfavorite | `developerGetV1AppsModulesFavoritesRecordIdGuidState` |

[]()

**Notifications (`notifications`)**

API bases: `/api/modules/notifications`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `4`; Developer `4` |
| Add / create / execute | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Edit / update / modify | Tenant `2`; Developer `2` |
| Delete / remove / deactivate | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (6):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/notifications` | List | `ListAsync` |
| `GET` | `/api/modules/notifications/lego-catalog` | Lego Catalog | `LegoCatalogAsync` |
| `GET` | `/api/modules/notifications/lego-presentation` | Lego Presentation | `LegoPresentationAsync` |
| `GET` | `/api/modules/notifications/{notificationId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/modules/notifications/{notificationId:guid}/source-favorite` | Favorite / unfavorite | `SetFavoriteAsync` |
| `PUT` | `/api/modules/notifications/{notificationId:guid}/state` | State transition | `SetStateAsync` |

Developer API routes (6):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/notifications` | List / view | `developerGetV1AppsModulesNotifications` |
| `GET` | `/v1/apps/{saasAppId}/modules/notifications/lego-catalog` | List / view | `developerGetV1AppsModulesNotificationsLegoCatalog` |
| `GET` | `/v1/apps/{saasAppId}/modules/notifications/lego-presentation` | List / view | `developerGetV1AppsModulesNotificationsLegoPresentation` |
| `GET` | `/v1/apps/{saasAppId}/modules/notifications/{notificationId}` | List / view | `developerGetV1AppsModulesNotificationsNotificationIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/notifications/{notificationId}/source-favorite` | Favorite / unfavorite | `developerPutV1AppsModulesNotificationsNotificationIdGuidSourceFavorite` |
| `PUT` | `/v1/apps/{saasAppId}/modules/notifications/{notificationId}/state` | State transition | `developerPutV1AppsModulesNotificationsNotificationIdGuidState` |

[]()

**Dynamic Records (`dynamic-records`)**

API bases: `/api/modules/dynamic`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `8`; Developer `8` |
| Add / create / execute | Tenant `2`; Developer `2` |
| Edit / update / modify | Tenant `2`; Developer `2` |
| Delete / remove / deactivate | Tenant `1`; Developer `1` |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (13):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/dynamic` | Catalog | `CatalogAsync` |
| `POST` | `/api/modules/dynamic/caseflow-cases/{recordId:guid}/transition` | Transition Case Flow | `TransitionCaseFlowAsync` |
| `GET` | `/api/modules/dynamic/{moduleKey}` | List | `ListAsync` |
| `POST` | `/api/modules/dynamic/{moduleKey}` | Create | `CreateAsync` |
| `GET` | `/api/modules/dynamic/{moduleKey}/export` | Export | `ExportAsync` |
| `GET` | `/api/modules/dynamic/{moduleKey}/export/capability` | Get Export Capability | `GetExportCapabilityAsync` |
| `GET` | `/api/modules/dynamic/{moduleKey}/lego/catalog` | Lego Catalog | `LegoCatalogAsync` |
| `GET` | `/api/modules/dynamic/{moduleKey}/lookups/{lookupId:guid}` | Lego Lookup | `LegoLookupAsync` |
| `GET` | `/api/modules/dynamic/{moduleKey}/schema` | Schema / field metadata | `SchemaAsync` |
| `DELETE` | `/api/modules/dynamic/{moduleKey}/{recordId:guid}` | Delete | `DeleteAsync` |
| `GET` | `/api/modules/dynamic/{moduleKey}/{recordId:guid}` | Get | `GetAsync` |
| `PUT` | `/api/modules/dynamic/{moduleKey}/{recordId:guid}` | Update | `UpdateAsync` |
| `PUT` | `/api/modules/dynamic/{moduleKey}/{recordId:guid}/favorite` | Favorite / unfavorite | `FavoriteAsync` |

Developer API routes (13):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic` | List / view | `developerGetV1AppsModulesDynamic` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/caseflow-cases/{recordId}/transition` | Add / create / execute | `developerPostV1AppsModulesDynamicCaseflowCasesRecordIdGuidTransition` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/export` | List / view | `developerGetV1AppsModulesDynamicModuleKeyExport` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/export/capability` | List / view | `developerGetV1AppsModulesDynamicModuleKeyExportCapability` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/lego/catalog` | List / view | `developerGetV1AppsModulesDynamicModuleKeyLegoCatalog` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/lookups/{lookupId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyLookupsLookupIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/schema` | Schema / field metadata | `developerGetV1AppsModulesDynamicModuleKeySchema` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` |

[]()

**ActiveWorkplace (`active-workplace`)**

API bases: `/api/modules/active-workplace`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `7`; Developer `7` |
| Add / create / execute | Tenant `5`; Developer `5` |
| Edit / update / modify | Tenant `1`; Developer `1` |
| Delete / remove / deactivate | Tenant `1`; Developer `1` |
| Favorite / unfavorite | No direct route; use [Favorites](#first-class-favorites)  only for supported authorized Records |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | Tenant `1`; Developer `1` |

Tenant runtime routes (14):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/active-workplace` | List | `ListAsync` |
| `POST` | `/api/modules/active-workplace` | Create | `CreateAsync` |
| `GET` | `/api/modules/active-workplace/lego/catalog` | Lego Catalog | `LegoCatalog` |
| `GET` | `/api/modules/active-workplace/lego/lookups/{lookupId:guid}` | Lego Lookup | `LegoLookupAsync` |
| `GET` | `/api/modules/active-workplace/lego/presentation` | Presentation metadata | `LegoPresentationAsync` |
| `GET` | `/api/modules/active-workplace/{activeWorkplaceId:guid}` | Get | `GetAsync` |
| `PATCH` | `/api/modules/active-workplace/{activeWorkplaceId:guid}` | Update | `UpdateAsync` |
| `POST` | `/api/modules/active-workplace/{activeWorkplaceId:guid}/activity` | Add / view activity | `RecordActivityAsync` |
| `POST` | `/api/modules/active-workplace/{activeWorkplaceId:guid}/graph/refresh` | Refresh Graph | `RefreshGraphAsync` |
| `POST` | `/api/modules/active-workplace/{activeWorkplaceId:guid}/participants` | Participant management | `AddParticipantAsync` |
| `GET` | `/api/modules/active-workplace/{activeWorkplaceId:guid}/participants/catalog` | List / view | `ParticipantCatalogAsync` |
| `DELETE` | `/api/modules/active-workplace/{activeWorkplaceId:guid}/participants/{activeWorkplaceParticipantId:guid}` | Participant management | `RemoveParticipantAsync` |
| `GET` | `/api/modules/active-workplace/{activeWorkplaceId:guid}/playback` | Playback / history | `PlaybackAsync` |
| `POST` | `/api/modules/active-workplace/{activeWorkplaceId:guid}/status` | Status transition | `SetStatusAsync` |

Developer API routes (14):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/active-workplace` | List / view | `developerGetV1AppsModulesActiveWorkplace` |
| `POST` | `/v1/apps/{saasAppId}/modules/active-workplace` | Add / create / execute | `developerPostV1AppsModulesActiveWorkplace` |
| `GET` | `/v1/apps/{saasAppId}/modules/active-workplace/lego/catalog` | List / view | `developerGetV1AppsModulesActiveWorkplaceLegoCatalog` |
| `GET` | `/v1/apps/{saasAppId}/modules/active-workplace/lego/lookups/{lookupId}` | List / view | `developerGetV1AppsModulesActiveWorkplaceLegoLookupsLookupIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/active-workplace/lego/presentation` | Presentation metadata | `developerGetV1AppsModulesActiveWorkplaceLegoPresentation` |
| `GET` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}` | List / view | `developerGetV1AppsModulesActiveWorkplaceActiveWorkplaceIdGuid` |
| `PATCH` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}` | Edit / update / modify | `developerPatchV1AppsModulesActiveWorkplaceActiveWorkplaceIdGuid` |
| `POST` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/activity` | Add / view activity | `developerPostV1AppsModulesActiveWorkplaceActiveWorkplaceIdGuidActivity` |
| `POST` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/graph/refresh` | Add / create / execute | `developerPostV1AppsModulesActiveWorkplaceActiveWorkplaceIdGuidGraphRefresh` |
| `POST` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/participants` | Participant management | `developerPostV1AppsModulesActiveWorkplaceActiveWorkplaceIdGuidParticipants` |
| `GET` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/participants/catalog` | List / view | `developerGetV1AppsModulesActiveWorkplaceActiveWorkplaceIdGuidParticipantsCatalog` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/participants/{activeWorkplaceParticipantId}` | Participant management | `developerDeleteV1AppsModulesActiveWorkplaceActiveWorkplaceIdGuidParticipantsActiveWorkplaceParticipantIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/playback` | Playback / history | `developerGetV1AppsModulesActiveWorkplaceActiveWorkplaceIdGuidPlayback` |
| `POST` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/status` | Status transition | `developerPostV1AppsModulesActiveWorkplaceActiveWorkplaceIdGuidStatus` |

[]()

**Record relations (`record-relations`)**

API bases: `/api/modules/record-graph`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `5`; Developer `5` |
| Add / create / execute | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Edit / update / modify | Tenant `3`; Developer `3` |
| Delete / remove / deactivate | Tenant `2`; Developer `2` |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | Tenant `10`; Developer `10` |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (10):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `DELETE` | `/api/modules/record-graph/knowledge-relations/{recordRelationId:guid}` | Relationship graph | `UnlinkKnowledgeAsync` |
| `GET` | `/api/modules/record-graph/records` | Relationship graph | `SearchAsync` |
| `DELETE` | `/api/modules/record-graph/relations/{recordRelationId:guid}` | Associate / remove relationship | `RemoveRelationAsync` |
| `GET` | `/api/modules/record-graph/{recordId:guid}` | Relationship graph | `GetAsync` |
| `PUT` | `/api/modules/record-graph/{recordId:guid}/favorite` | Favorite / unfavorite | `SetFavoriteAsync` |
| `GET` | `/api/modules/record-graph/{recordId:guid}/knowledge` | Relationship graph | `RelatedKnowledgeAsync` |
| `PUT` | `/api/modules/record-graph/{recordId:guid}/knowledge` | Associate / add | `LinkKnowledgeAsync` |
| `GET` | `/api/modules/record-graph/{recordId:guid}/knowledge/candidates` | Relationship graph | `ContextualKnowledgeAsync` |
| `GET` | `/api/modules/record-graph/{recordId:guid}/relations` | List / view | `ListRelatedAsync` |
| `PUT` | `/api/modules/record-graph/{recordId:guid}/relations` | Associate / add | `AddRelationAsync` |

Developer API routes (10):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/knowledge-relations/{recordRelationId}` | Relationship graph | `developerDeleteV1AppsModulesRecordGraphKnowledgeRelationsRecordRelationIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/records` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecords` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesRecordGraphRecordIdGuidFavorite` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/knowledge` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuidKnowledge` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/knowledge` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidKnowledge` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/knowledge/candidates` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuidKnowledgeCandidates` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | List / view | `developerGetV1AppsModulesRecordGraphRecordIdGuidRelations` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` |

[]()

**Record activity (`record-activity`)**

API bases: `/api/modules/record-activity`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `3`; Developer `2` |
| Add / create / execute | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Edit / update / modify | Tenant `1`; Developer `1` |
| Delete / remove / deactivate | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | Tenant `4`; Developer `3` |

Tenant runtime routes (4):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/record-activity/records` | Activity / audit history | `SearchAsync` |
| `GET` | `/api/modules/record-activity/{recordId:guid}` | Activity / audit history | `GetAsync` |
| `PUT` | `/api/modules/record-activity/{recordId:guid}/favorite` | Favorite / unfavorite | `SetFavoriteAsync` |
| `GET` | `/api/modules/record-activity/{recordId:guid}/history` | Activity / audit history | `ReadAsync` |

Developer API routes (3):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/records` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecords` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesRecordActivityRecordIdGuidFavorite` |

[]()

**Global secured search (`global-search`)**

API bases: `/api/modules/global-search`.

Day-to-day action coverage:

| Usability action | Direct route coverage |
| --- | --- |
| List / search / view | Tenant `2`; Developer `2` |
| Add / create / execute | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Edit / update / modify | Tenant `1`; Developer `1` |
| Delete / remove / deactivate | Not published as a direct action; this capability may be derived/read-only or action-specific |
| Favorite / unfavorite | Tenant `1`; Developer `1` |
| Associate / relationships | No direct route; use [Record relations](#first-class-record-relations)  only for supported authorized Records |
| Files / attachments / evidence | No direct route; use [Files](#first-class-files)  only for supported authorized Records |
| Activity / audit | No direct route; use [Record activity](#first-class-record-activity)  only for supported authorized Records |

Tenant runtime routes (3):

| Method | Route | Action | Controller action |
| --- | --- | --- | --- |
| `GET` | `/api/modules/global-search` | Search | `SearchAsync` |
| `GET` | `/api/modules/global-search/count` | Count | `CountAsync` |
| `PUT` | `/api/modules/global-search/records/{recordId:guid}/favorite` | Favorite / unfavorite | `SetFavoriteAsync` |

Developer API routes (3):

| Method | Route | Action | OpenAPI operationId |
| --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/global-search` | List / view | `developerGetV1AppsModulesGlobalSearch` |
| `GET` | `/v1/apps/{saasAppId}/modules/global-search/count` | List / view | `developerGetV1AppsModulesGlobalSearchCount` |
| `PUT` | `/v1/apps/{saasAppId}/modules/global-search/records/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesGlobalSearchRecordsRecordIdGuidFavorite` |

First-class totals: **292 tenant-runtime routes** and **273 Developer API routes** across 25 capabilities. These are unique route totals; discovery pages reuse the owning capabilities' routes, so per-capability counts must not be added together.

## Console-only capabilities

These tenant-runtime routes are intentionally absent from the promoted Developer API surface and are governed by the reviewed allow-list `tools/api-route-inventory-console-only-allowlist.json`. Here, console-only means tenant-runtime-only, not Builder Console; workflow approval is made by a signed-in user in Universal Inbox:

| Method | Tenant-runtime route | Why no Developer API equivalent is published |
| --- | --- | --- |
| `PUT` | `/api/goclaw/agents/{goClawAgentId:guid}/authority` | GoClaw agent authority is managed by signed-in tenant users in the tenant app; no delegated Developer API equivalent is published. |
| `POST` | `/api/inbox/items/{inboxItemId:guid}/workflow-approval` | Approval is made by a signed-in user in Universal Inbox; no Developer API equivalent is published, and the ActivityVersion fence remains in force. |
| `GET` | `/api/modules/record-activity/{recordId:guid}/history` | Secured record change history is available to signed-in tenant users through the native record envelope. The reviewed history release deliberately excludes this route from the Developer API; broader audit producer coverage remains separate. |

## Native-only operations

These routes retain their signed-in tenant boundary. Their presence does not grant Developer credentials access.

| Method | Native route | Boundary |
| --- | --- | --- |
| `GET` | `/api/modules/ai-insights/settings` | Organization-owner AI Insights producer settings; no delegated Developer API authority contract is reviewed. |
| `PUT` | `/api/modules/ai-insights/settings` | Organization-owner AI Insights producer settings; no delegated Developer API authority contract is reviewed. |
| `POST` | `/api/modules/ai-insights/settings/directives` | Organization-owner AI Insights producer settings; no delegated Developer API authority contract is reviewed. |
| `PUT` | `/api/modules/ai-insights/settings/directives/{directiveId:guid}` | Organization-owner AI Insights producer settings; no delegated Developer API authority contract is reviewed. |
| `PUT` | `/api/modules/ai-insights/settings/starters/{directiveId:guid}` | Organization-owner AI Insights producer settings; no delegated Developer API authority contract is reviewed. |
| `GET` | `/api/modules/contacts/list-preferences` | Signed-in tenant presentation preferences and audited secure-field operations; no delegated Developer API authority contract is published. |
| `PUT` | `/api/modules/contacts/list-preferences/{scope}` | Signed-in tenant presentation preferences and audited secure-field operations; no delegated Developer API authority contract is published. |
| `PUT` | `/api/modules/contacts/{recordId:guid}/secure-fields/{fieldDefinitionId:guid}` | Signed-in tenant presentation preferences and audited secure-field operations; no delegated Developer API authority contract is published. |
| `POST` | `/api/modules/contacts/{recordId:guid}/secure-fields/{fieldDefinitionId:guid}/reveal` | Signed-in tenant presentation preferences and audited secure-field operations; no delegated Developer API authority contract is published. |
| `GET` | `/api/modules/files/personal-limit` | Signed-in person's personal file limit and its organization-owner setting; no delegated Developer API authority contract is reviewed. |
| `PUT` | `/api/modules/files/personal-limit` | Signed-in person's personal file limit and its organization-owner setting; no delegated Developer API authority contract is reviewed. |
| `GET` | `/api/tenant/native-message-attachments/{recordId:guid}/content` | Native message attachment transport is not a promoted module action. |

## Deferred Developer API routes

These native routes remain explicitly deferred under the existing owner policy. Their presence in the native catalog does not publish them or create credential scopes.

| Method | Native route | Reviewed deferral |
| --- | --- | --- |
| `GET` | `/api/modules/mail-reader/mailboxes` | Mailbox administration, credentials, compose/send and archive remain deferred pending their separate provider and lifecycle acceptance. The four restored message operations use verified installed secured SQL. |
| `POST` | `/api/modules/mail-reader/mailboxes` | Mailbox administration, credentials, compose/send and archive remain deferred pending their separate provider and lifecycle acceptance. The four restored message operations use verified installed secured SQL. |
| `PUT` | `/api/modules/mail-reader/mailboxes/{mailboxId:guid}` | Mailbox administration, credentials, compose/send and archive remain deferred pending their separate provider and lifecycle acceptance. The four restored message operations use verified installed secured SQL. |
| `POST` | `/api/modules/mail-reader/mailboxes/{mailboxRecordId:guid}/compose` | Mailbox administration, credentials, compose/send and archive remain deferred pending their separate provider and lifecycle acceptance. The four restored message operations use verified installed secured SQL. |
| `PUT` | `/api/modules/mail-reader/mailboxes/{mailboxRecordId:guid}/credentials/{purpose}` | Mailbox administration, credentials, compose/send and archive remain deferred pending their separate provider and lifecycle acceptance. The four restored message operations use verified installed secured SQL. |
| `POST` | `/api/modules/mail-reader/{recordId:guid}/archive` | Mailbox administration, credentials, compose/send and archive remain deferred pending their separate provider and lifecycle acceptance. The four restored message operations use verified installed secured SQL. |

## 2. Build This product routes

Origins are `recipe:<step-key>` for canonical Developer API recipe steps and `solution-manifest` for additional operation IDs explicitly present in the runnable production solution. An operation can have both origins.

**CrewOS (`crew-os`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.goclaw.read`, `modules.goclaw.write`, `modules.record-graph.read`, `modules.universal-inbox.read`.

Composed first-class capability route sets: [dynamic-records](#first-class-dynamic-records), [files](#first-class-files), [goclaw](#first-class-goclaw), [record-activity](#first-class-record-activity)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `crewos-agent-profiles` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (deactivate) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `crewos-work-requests` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (close) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `crewos-ratings` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `crewos-approval-inbox` | `crewos-work-requests` | Planning is read-only; this surface applies only canonical approve, reject, retry, or take-over controls and never edits source records directly. |
| `crewos-execution-timeline` | `crewos-work-requests` | Execution evidence is an immutable derived trail; lifecycle changes occur on the source work request or governed approval. |

Direct recipe/solution operations (13):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/goclaw/approvals` | List / view | `developerGetV1AppsGoclawApprovals` | `recipe:list-approvals` |
| `POST` | `/v1/apps/{saasAppId}/goclaw/approvals/{suggestionBatchId}/approve` | Approve | `developerPostV1AppsGoclawApprovalsSuggestionBatchIdGuidApprove` | `recipe:approve-batch` |
| `GET` | `/v1/apps/{saasAppId}/inbox/items` | List / view | `developerGetV1AppsInboxItems` | `recipe:verify-inbox` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `recipe:open-context, solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |

**SignalIQ (`signal-iq`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.ai-insights.read`, `modules.ai-insights.write`, `modules.contacts.read`, `modules.record-graph.read`.

Composed first-class capability route sets: [ai-insights](#first-class-ai-insights), [dynamic-records](#first-class-dynamic-records), [files](#first-class-files), [goclaw](#first-class-goclaw)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `signaliq-accounts` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `signaliq-contacts` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `signaliq-opportunities` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (close) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `signaliq-signals` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `signaliq-score-snapshots` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `signaliq-recommendations` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (close) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `signaliq-revenue-command-center` | `signaliq-accounts` | The command center ranks and explains permitted records; lifecycle changes occur on the native account, opportunity, signal, score, or recommendation record. |
| `signaliq-secured-insights` | `signaliq-recommendations` | AI Insights are secured findings with personal feed state, not authorization to mutate CRM records. |
| `signaliq-action-approvals` | `signaliq-recommendations` | Planning is read-only; material next-best actions use the canonical permission and ActivityVersion-fenced approval chain. |

Direct recipe/solution operations (14):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/ai-insights` | List / view | `developerGetV1AppsModulesAiInsights` | `recipe:list-insights` |
| `GET` | `/v1/apps/{saasAppId}/modules/ai-insights/{insightId}` | List / view | `developerGetV1AppsModulesAiInsightsInsightIdGuid` | `recipe:open-insight` |
| `PUT` | `/v1/apps/{saasAppId}/modules/ai-insights/{insightId}/state` | State transition | `developerPutV1AppsModulesAiInsightsInsightIdGuidState` | `recipe:set-state` |
| `GET` | `/v1/apps/{saasAppId}/modules/contacts` | List / view | `developerGetV1AppsModulesContacts` | `recipe:find-account` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `recipe:load-graph, solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |

**Resolve (`resolve`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.conversations.write`, `modules.knowledge-articles.read`, `modules.universal-inbox.read`, `modules.universal-inbox.write`.

Composed first-class capability route sets: [ai-insights](#first-class-ai-insights), [conversations](#first-class-conversations), [dynamic-records](#first-class-dynamic-records), [goclaw](#first-class-goclaw), [knowledge-core](#first-class-knowledge-core), [universal-inbox](#first-class-universal-inbox)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `resolve-customer-contexts` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `resolve-issues` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (close) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `resolve-resolution-suggestions` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `resolve-escalations` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (close) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `resolve-universal-inbox` | `resolve-issues` | Universal Inbox is the attention layer; communication lifecycle remains on the native Conversation and issue lifecycle remains on Resolve Issues. |
| `resolve-policy-findings` | `resolve-resolution-suggestions` | Cited AI findings do not authorize customer-facing mutations; actions require policy or human approval. |
| `resolve-action-approvals` | `resolve-resolution-suggestions` | Planning is read-only and approval retains the current Inbox ActivityVersion fence. |

Direct recipe/solution operations (15):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/inbox/items` | List / view | `developerGetV1AppsInboxItems` | `recipe:list-work` |
| `GET` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}` | List / view | `developerGetV1AppsInboxItemsInboxItemIdGuid` | `recipe:open-ticket` |
| `PUT` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}/human-state` | Human state / resolution | `developerPutV1AppsInboxItemsInboxItemIdGuidHumanState` | `recipe:resolve` |
| `POST` | `/v1/apps/{saasAppId}/modules/conversations/{recordId}/messages` | Message / reply | `developerPostV1AppsModulesConversationsRecordIdGuidMessages` | `recipe:reply` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core` | List / view | `developerGetV1AppsModulesKnowledgeCore` | `recipe:find-policy` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |

**LaunchPilot (`launch-pilot`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.dynamic-records.read`, `modules.dynamic-records.write`, `modules.files.write`, `modules.goclaw.read`.

Composed first-class capability route sets: [ai-insights](#first-class-ai-insights), [dynamic-records](#first-class-dynamic-records), [files](#first-class-files), [universal-inbox](#first-class-universal-inbox)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `launchpilot-campaigns` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `launchpilot-audiences` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `launchpilot-assets` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `launchpilot-channel-runs` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (cancel) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `launchpilot-experiments` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (close) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `launchpilot-performance-snapshots` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `launchpilot-campaign-readiness` | `launchpilot-campaigns` | Readiness and AI findings explain permitted campaign evidence but never authorize audience disclosure, claims, spend, or activation. |
| `launchpilot-approval-attention` | `launchpilot-channel-runs` | Universal Inbox points to approval work; the managed channel run retains launch state and frozen inputs. |
| `launchpilot-optimization-findings` | `launchpilot-performance-snapshots` | Performance findings may propose a bounded experiment or budget adjustment but cannot silently activate channels or move spend. |

Direct recipe/solution operations (13):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/goclaw/approvals` | List / view | `developerGetV1AppsGoclawApprovals` | `recipe:inspect-approvals` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `recipe:create-campaign, solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/schema` | Schema / field metadata | `developerGetV1AppsModulesDynamicModuleKeySchema` | `recipe:read-schema` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `recipe:verify-campaign, solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/files/upload` | File / attachment | `developerPostV1AppsModulesFilesUpload` | `recipe:upload-asset` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |

**Northstar (`northstar`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.ai-insights.read`, `modules.ai-insights.write`, `modules.global-search.read`, `modules.record-activity.read`, `modules.record-graph.read`.

Composed first-class capability route sets: [ai-insights](#first-class-ai-insights), [dynamic-records](#first-class-dynamic-records), [files](#first-class-files), [goclaw](#first-class-goclaw)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `northstar-metric-definitions` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (retire) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `northstar-metric-observations` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `northstar-forecasts` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (retire) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `northstar-signals` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (close) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `northstar-scenarios` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `northstar-briefings` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `northstar-executive-scorecard` | `northstar-metric-definitions` | The scorecard summarizes currently permitted managed metric and observation records and links back to their native lifecycle. |
| `northstar-synthesis` | `northstar-signals` | AI synthesis explains authorized evidence and uncertainty but cannot invent or overwrite metrics, forecasts, or decisions. |
| `northstar-decision-approvals` | `northstar-briefings` | Planning and approval attention do not mutate operating systems; approved follow-up uses the canonical governed action chain. |

Direct recipe/solution operations (13):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/ai-insights` | List / view | `developerGetV1AppsModulesAiInsights` | `recipe:list-insights` |
| `PUT` | `/v1/apps/{saasAppId}/modules/ai-insights/{insightId}/state` | State transition | `developerPutV1AppsModulesAiInsightsInsightIdGuidState` | `recipe:record-disposition` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/global-search` | List / view | `developerGetV1AppsModulesGlobalSearch` | `recipe:search` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `recipe:load-history, solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `recipe:load-evidence, solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |

**TeamBox (`team-box`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.conversations.read`, `modules.conversations.write`, `modules.universal-inbox.read`, `modules.universal-inbox.write`.

Composed first-class capability route sets: [ai-insights](#first-class-ai-insights), [conversations](#first-class-conversations), [dynamic-records](#first-class-dynamic-records), [files](#first-class-files), [goclaw](#first-class-goclaw), [universal-inbox](#first-class-universal-inbox)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `teambox-channel-intake-policies` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (deactivate) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `teambox-queues` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (deactivate) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `teambox-routing-rules` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (deactivate) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `teambox-classification-reviews` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `teambox-sla-policies` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (deactivate) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `teambox-handoff-playbooks` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (deactivate) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `teambox-attention-queue` | `teambox-queues` | Universal Inbox is the attention and ownership projection; native conversations and their source business records keep their lifecycle and history. |
| `teambox-triage-insights` | `teambox-classification-reviews` | AI classification and summaries expose permitted evidence and uncertainty; reviewers change managed disposition without overwriting the native conversation. |
| `teambox-action-approvals` | `teambox-handoff-playbooks` | Prepared customer replies and material operations stay fenced to the Inbox ActivityVersion and require configured policy or human approval. |

Direct recipe/solution operations (15):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/inbox/items` | List / view | `developerGetV1AppsInboxItems` | `recipe:list-attention` |
| `GET` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}` | List / view | `developerGetV1AppsInboxItemsInboxItemIdGuid` | `recipe:open-item` |
| `PUT` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}/human-state` | Human state / resolution | `developerPutV1AppsInboxItemsInboxItemIdGuidHumanState` | `recipe:claim-or-complete` |
| `GET` | `/v1/apps/{saasAppId}/modules/conversations/{recordId}` | List / view | `developerGetV1AppsModulesConversationsRecordIdGuid` | `recipe:open-conversation` |
| `POST` | `/v1/apps/{saasAppId}/modules/conversations/{recordId}/messages` | Message / reply | `developerPostV1AppsModulesConversationsRecordIdGuidMessages` | `recipe:reply` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |

**RelateEverything (`relate-everything`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.contacts.write`, `modules.global-search.read`, `modules.record-graph.read`, `modules.record-graph.write`.

Composed first-class capability route sets: [ai-insights](#first-class-ai-insights), [contacts](#first-class-contacts), [dynamic-records](#first-class-dynamic-records), [files](#first-class-files), [global-search](#first-class-global-search), [record-relations](#first-class-record-relations)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `relateeverything-companies` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `relateeverything-workstreams` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `relateeverything-opportunities` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (close) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `relateeverything-relationship-contexts` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `relateeverything-duplicate-reviews` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `relateeverything-connected-automations` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (deactivate) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `relateeverything-connected-search` | `relateeverything-companies` | Search discovers only currently authorized canonical records and links to the owning module lifecycle. |
| `relateeverything-permissioned-graph` | `relateeverything-relationship-contexts` | Graph traversal omits inaccessible nodes and incident edges; relation creation and removal remain explicit secured operations. |
| `relateeverything-context-insights` | `relateeverything-duplicate-reviews` | AI summarizes currently authorized connected context and marks inferred links separately from confirmed facts. |

Direct recipe/solution operations (12):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `POST` | `/v1/apps/{saasAppId}/modules/contacts` | Add / create / execute | `developerPostV1AppsModulesContacts` | `recipe:create-contact` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/global-search` | List / view | `developerGetV1AppsModulesGlobalSearch` | `recipe:search` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `recipe:read-graph, solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `recipe:relate-record, solution-manifest` |

**CustomerPortal (`customer-portal`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `app-credential-then-delegated-user`. Required recipe scopes: `modules.conversations.read`, `modules.files.read`, `tenant-accounts.write`, `tenant-users.read`, `tenant-users.tokens.issue`, `tenant-users.write`.

Composed first-class capability route sets: [dynamic-records](#first-class-dynamic-records), [files](#first-class-files)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `customerportal-requests` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (close) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `customerportal-milestones` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `customerportal-approvals` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (revoke) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `customerportal-shared-updates` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `customerportal-internal-operations` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `customerportal-visibility-reviews` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `customerportal-global-search` | `customerportal-requests` | Search is derived and opens the native secured record lifecycle. |
| `customerportal-relationship-graph` | `customerportal-requests` | Graph traversal returns only independently authorized nodes and edges. |
| `customerportal-internal-ai` | `customerportal-internal-operations` | AI Insights are internal read-only synthesis and never authorize customer-facing action. |

Direct recipe/solution operations (16):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `POST` | `/v1/apps/{saasAppId}/accounts` | Add / create / execute | `developerHeadlessIdentityCreateAccount` | `recipe:create-account` |
| `GET` | `/v1/apps/{saasAppId}/accounts/{appAccountId}/security-catalog` | List / view | `developerHeadlessIdentityGetSecurityCatalog` | `recipe:read-security-catalog` |
| `POST` | `/v1/apps/{saasAppId}/accounts/{appAccountId}/users` | Add / create / execute | `developerHeadlessIdentityCreateUser` | `recipe:create-user` |
| `GET` | `/v1/apps/{saasAppId}/modules/conversations` | List / view | `developerGetV1AppsModulesConversations` | `recipe:list-shared-conversations` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/files` | File / attachment | `developerGetV1AppsModulesFiles` | `recipe:list-shared-files` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/user-token-exchanges` | Add / create / execute | `developerHeadlessIdentityExchangeUserToken` | `recipe:issue-user-token` |

**CompanyIQ (`company-iq`)**

Readiness: **withheld - not buildable in this kit** — its real Developer API operations and GPU/producer readiness lanes are not available in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `ai.read`, `ai.write`, `modules.knowledge-articles.write`, `modules.record-graph.write`.

Composed first-class capability route sets: [dynamic-records](#first-class-dynamic-records), [files](#first-class-files)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `companyiq-source-catalog` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `companyiq-business-context` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `companyiq-intelligence-runs` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (cancel) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `companyiq-opportunity-insights` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `companyiq-evidence-reviews` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `companyiq-semantic-search` | `companyiq-source-catalog` | Search returns only independently authorized source evidence and links back to the native owner. |
| `companyiq-native-ai-insights` | `companyiq-opportunity-insights` | The feed is a secured projection; lifecycle remains on the underlying insight and governed action records. |

Direct recipe/solution operations (15):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `POST` | `/v1/apps/{saasAppId}/ai/search` | Search | `developerAiSearch` | `recipe:search` |
| `POST` | `/v1/apps/{saasAppId}/ai/sources/records/{recordId}/ingest` | Add / create / execute | `developerAiIngest` | `recipe:ingest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCore` | `recipe:create-knowledge` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/publish` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreRecordIdGuidPublish` | `recipe:publish` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/knowledge` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidKnowledge` | `recipe:connect-record` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |

**OpsAtlas (`ops-atlas`)**

Readiness: **withheld - not buildable in this kit** — its real Developer API operations and GPU/producer readiness lanes are not available in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.knowledge-articles.read`, `modules.knowledge-articles.write`.

Composed first-class capability route sets: [dynamic-records](#first-class-dynamic-records), [files](#first-class-files), [knowledge-core](#first-class-knowledge-core)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `opsatlas-operating-domains` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `opsatlas-source-registers` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `opsatlas-review-programs` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (close) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `opsatlas-gap-triage` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (close) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `opsatlas-governed-actions` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (cancel) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `opsatlas-secured-answers` | `opsatlas-source-registers` | Answer synthesis is read-only and opens exact published source revisions; unsupported answers create questions instead of fabricating. |
| `opsatlas-knowledge-health` | `opsatlas-gap-triage` | Health is a secured projection; lifecycle remains on Knowledge items, questions, reviews, and triage records. |

Direct recipe/solution operations (16):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCore` | `recipe:create-article` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/gaps` | List / view | `developerGetV1AppsModulesKnowledgeCoreGaps` | `recipe:review-gaps` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/health` | List / view | `developerGetV1AppsModulesKnowledgeCoreHealth` | `recipe:review-health` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/owners` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreRecordIdGuidOwners` | `recipe:assign-owner` |
| `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/publish` | Add / create / execute | `developerPostV1AppsModulesKnowledgeCoreRecordIdGuidPublish` | `recipe:publish` |
| `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/revisions` | List / view | `developerGetV1AppsModulesKnowledgeCoreRecordIdGuidRevisions` | `recipe:verify-revisions` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |

**Headless SaaS DB (`headless-saas-db`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `app-credential-then-delegated-user`. Required recipe scopes: `modules.dynamic-records.write`, `modules.record-graph.read`, `modules.record-graph.write`, `records.read`, `records.write`, `tenant-accounts.write`, `tenant-users.tokens.issue`, `tenant-users.write`, `webhooks.write`.

Composed first-class capability route sets: [dynamic-records](#first-class-dynamic-records), [files](#first-class-files)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `headless-domain-records` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `headless-api-client-profiles` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (revoke) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `headless-inbound-contracts` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (deactivate) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `headless-webhook-policies` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (deactivate) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `headless-operation-evidence` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `headless-native-api-clients` | `headless-api-client-profiles` | Profiles link to the native Developer Console credential lifecycle; one-time secrets are never copied into dynamic records or browser output. |
| `headless-delivery-diagnostics` | `headless-operation-evidence` | Diagnostics are bounded projections; retries and state changes remain on authorized native Developer API operations. |

Direct recipe/solution operations (20):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `POST` | `/v1/apps/{saasAppId}/accounts` | Add / create / execute | `developerHeadlessIdentityCreateAccount` | `recipe:create-account` |
| `POST` | `/v1/apps/{saasAppId}/accounts/{appAccountId}/users` | Add / create / execute | `developerHeadlessIdentityCreateUser` | `recipe:create-user` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `recipe:favorite-record, solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `recipe:remove-relation, solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `recipe:inspect-graph, solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `recipe:add-relation, solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/objects/{objectKey}/records` | Add / create / execute | `developerRecordsCreate` | `recipe:create-record` |
| `DELETE` | `/v1/apps/{saasAppId}/objects/{objectKey}/records/{recordId}` | Delete / remove / deactivate | `developerRecordsDelete` | `recipe:remove-record` |
| `GET` | `/v1/apps/{saasAppId}/objects/{objectKey}/records/{recordId}` | List / view | `developerRecordsGet` | `recipe:read-record` |
| `PATCH` | `/v1/apps/{saasAppId}/objects/{objectKey}/records/{recordId}` | Edit / update / modify | `developerRecordsUpdate` | `recipe:update-record` |
| `GET` | `/v1/apps/{saasAppId}/objects/{objectKey}/schema` | Schema / field metadata | `developerRecordsGetSchema` | `recipe:read-object-schema` |
| `POST` | `/v1/apps/{saasAppId}/user-token-exchanges` | Add / create / execute | `developerHeadlessIdentityExchangeUserToken` | `recipe:issue-token` |
| `POST` | `/v1/apps/{saasAppId}/webhooks` | Add / create / execute | `developerWebhookSubscriptionsCreate` | `recipe:create-webhook` |
| `PUT` | `/v1/apps/{saasAppId}/webhooks/{subscriptionId}` | Edit / update / modify | `developerWebhookSubscriptionsUpdate` | `recipe:deactivate-webhook` |

**CaseFlow (`case-flow`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.checklists-signoffs.write`, `modules.dynamic-records.read`, `modules.dynamic-records.write`, `modules.files.write`, `modules.universal-inbox.read`.

Composed first-class capability route sets: [ai-insights](#first-class-ai-insights), [checklists-signoffs](#first-class-checklists-signoffs), [dynamic-records](#first-class-dynamic-records), [files](#first-class-files), [record-activity](#first-class-record-activity), [universal-inbox](#first-class-universal-inbox)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `caseflow-cases` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (close) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `caseflow-parties` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `caseflow-stage-transitions` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `caseflow-tasks` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (close) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `caseflow-evidence` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `caseflow-decisions` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `caseflow-approvals` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `caseflow-inbox` | `caseflow-approvals` | Universal Inbox is the attention and approval surface; cases, decisions and signoff checklists retain native lifecycle ownership. |
| `caseflow-ai-review` | `caseflow-decisions` | AI may summarize permitted evidence and suggest next work but cannot decide or advance a case. |
| `caseflow-activity` | `caseflow-cases` | Activity is an audit projection with links back to the secured native case records. |

Direct recipe/solution operations (15):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/inbox/items` | List / view | `developerGetV1AppsInboxItems` | `recipe:verify-attention` |
| `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs` | Add / create / execute | `developerPostV1AppsModulesChecklistsSignoffsRuns` | `recipe:start-checklist` |
| `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs/{checklistRunId}/submit` | Submit workflow | `developerPostV1AppsModulesChecklistsSignoffsRunsChecklistRunIdGuidSubmit` | `recipe:submit-stage` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `recipe:create-case, solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/schema` | Schema / field metadata | `developerGetV1AppsModulesDynamicModuleKeySchema` | `recipe:read-case-schema` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/files/upload` | File / attachment | `developerPostV1AppsModulesFilesUpload` | `recipe:upload-proof` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |

**AssetOps (`asset-ops`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.checklists-signoffs.write`, `modules.dynamic-records.write`, `modules.files.write`, `modules.record-graph.read`, `modules.work-orders.write`.

Composed first-class capability route sets: [ai-insights](#first-class-ai-insights), [checklists-signoffs](#first-class-checklists-signoffs), [contacts](#first-class-contacts), [dynamic-records](#first-class-dynamic-records), [files](#first-class-files), [record-activity](#first-class-record-activity), [work-orders](#first-class-work-orders)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `assetops-sites` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (deactivate) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `assetops-assets` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (retire) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `assetops-inspection-findings` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `assetops-part-usages` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `assetops-service-events` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (archive) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `assetops-condition-signals` | `assetops-assets` | AI condition summaries are suggestions over permitted history and cannot mutate asset or work state. |
| `assetops-activity` | `assetops-service-events` | Activity is an audit projection with links back to the secured native record. |

Direct recipe/solution operations (13):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs` | Add / create / execute | `developerPostV1AppsModulesChecklistsSignoffsRuns` | `recipe:start-inspection` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `recipe:create-asset, solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/files/upload` | File / attachment | `developerPostV1AppsModulesFilesUpload` | `recipe:upload-evidence` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `recipe:verify-graph, solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/work-orders` | Add / create / execute | `developerPostV1AppsModulesWorkOrders` | `recipe:create-work-order` |

**ActiveWorkplace (`active-workplace`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.active-workplace.read`, `modules.active-workplace.write`.

Composed first-class capability route sets: [active-workplace](#first-class-active-workplace), [dynamic-records](#first-class-dynamic-records), [universal-inbox](#first-class-universal-inbox)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `activeworkplace-work-items` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (close) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |
| `activeworkplace-playbooks` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (retire) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `activeworkplace-playback` | `activeworkplace-work-items` | Graph Playback re-applies current authorization and exposes no mutation controls. |
| `activeworkplace-inbox` | `activeworkplace-work-items` | Universal Inbox is the shared attention layer; the root Record and workplace remain native owners. |

Direct recipe/solution operations (16):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `POST` | `/v1/apps/{saasAppId}/modules/active-workplace` | Add / create / execute | `developerPostV1AppsModulesActiveWorkplace` | `recipe:create-workplace` |
| `POST` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/activity` | Add / view activity | `developerPostV1AppsModulesActiveWorkplaceActiveWorkplaceIdGuidActivity` | `recipe:append-activity` |
| `POST` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/graph/refresh` | Add / create / execute | `developerPostV1AppsModulesActiveWorkplaceActiveWorkplaceIdGuidGraphRefresh` | `recipe:refresh-graph` |
| `POST` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/participants` | Participant management | `developerPostV1AppsModulesActiveWorkplaceActiveWorkplaceIdGuidParticipants` | `recipe:add-participant` |
| `GET` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/participants/catalog` | List / view | `developerGetV1AppsModulesActiveWorkplaceActiveWorkplaceIdGuidParticipantsCatalog` | `recipe:list-participants` |
| `GET` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/playback` | Playback / history | `developerGetV1AppsModulesActiveWorkplaceActiveWorkplaceIdGuidPlayback` | `recipe:playback` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |

**FieldService (`field-service`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.calendar.write`, `modules.checklists-signoffs.write`, `modules.contacts.read`, `modules.work-orders.write`.

Composed first-class capability route sets: [ai-insights](#first-class-ai-insights), [calendar](#first-class-calendar), [contacts](#first-class-contacts), [conversations](#first-class-conversations), [dynamic-records](#first-class-dynamic-records), [universal-inbox](#first-class-universal-inbox), [work-orders](#first-class-work-orders)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `change-requests` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (cancel) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `fieldservice-ai-assistant` | `change-requests` | The assistant returns cited permitted evidence and cannot mutate jobs, approvals or customer messages. |
| `fieldservice-inbox` | `change-requests` | Universal Inbox projects attention while native Records remain source of truth. |

Direct recipe/solution operations (16):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `POST` | `/v1/apps/{saasAppId}/modules/calendar` | Add / create / execute | `developerPostV1AppsModulesCalendar` | `recipe:schedule` |
| `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs` | Add / create / execute | `developerPostV1AppsModulesChecklistsSignoffsRuns` | `recipe:start-proof-checklist` |
| `GET` | `/v1/apps/{saasAppId}/modules/contacts` | List / view | `developerGetV1AppsModulesContacts` | `recipe:find-customer` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/work-orders` | Add / create / execute | `developerPostV1AppsModulesWorkOrders` | `recipe:create-job` |
| `PUT` | `/v1/apps/{saasAppId}/modules/work-orders/{recordId}/assignment` | Assignment update | `developerPutV1AppsModulesWorkOrdersRecordIdGuidAssignment` | `recipe:assign-technician` |
| `PUT` | `/v1/apps/{saasAppId}/modules/work-orders/{recordId}/status` | Status transition | `developerPutV1AppsModulesWorkOrdersRecordIdGuidStatus` | `recipe:complete-job` |

**Reservations (`reservations`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.reservations.read`, `modules.reservations.write`.

Composed first-class capability route sets: [calendar](#first-class-calendar), [contacts](#first-class-contacts), [dynamic-records](#first-class-dynamic-records), [reservations](#first-class-reservations)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `reservation-policies` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (retire) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `reservation-payment-state` | `reservation-policies` | Provider-synchronized payment state is displayed but never client-authored. |
| `reservation-capacity` | `reservation-policies` | Availability is derived from server-locked overlap checks, not editable counters. |

Direct recipe/solution operations (16):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/reservations/products` | List / view | `developerGetV1AppsModulesReservationsProducts` | `recipe:list-products` |
| `POST` | `/v1/apps/{saasAppId}/modules/reservations/products` | Add / create / execute | `developerPostV1AppsModulesReservationsProducts` | `recipe:publish-product` |
| `POST` | `/v1/apps/{saasAppId}/modules/reservations/purchase` | Add / create / execute | `developerPostV1AppsModulesReservationsPurchase` | `recipe:purchase` |
| `GET` | `/v1/apps/{saasAppId}/modules/reservations/{recordId}` | List / view | `developerGetV1AppsModulesReservationsRecordIdGuid` | `recipe:open-reservation` |
| `PUT` | `/v1/apps/{saasAppId}/modules/reservations/{recordId}/followups` | Edit / update / modify | `developerPutV1AppsModulesReservationsRecordIdGuidFollowups` | `recipe:set-follow-up` |
| `PUT` | `/v1/apps/{saasAppId}/modules/reservations/{recordId}/status` | Status transition | `developerPutV1AppsModulesReservationsRecordIdGuidStatus` | `recipe:set-status` |

**Checkoff & Approval (`checkoff-approval`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.checklists-signoffs.read`, `modules.checklists-signoffs.write`, `modules.files.write`.

Composed first-class capability route sets: [checklists-signoffs](#first-class-checklists-signoffs), [dynamic-records](#first-class-dynamic-records), [files](#first-class-files), [universal-inbox](#first-class-universal-inbox)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `verification-programs` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (retire) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `checklist-progress` | `verification-programs` | Progress is derived from versioned native run items and validated evidence. |
| `signoff-attention` | `verification-programs` | Universal Inbox projects the native Workflow approval and preserves its ActivityVersion fence. |

Direct recipe/solution operations (21):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `PUT` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/items/{checklistRunItemId}` | Edit / update / modify | `developerPutV1AppsModulesChecklistsSignoffsItemsChecklistRunItemIdGuid` | `recipe:complete-item` |
| `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/items/{checklistRunItemId}/proof` | File proof / evidence | `developerPostV1AppsModulesChecklistsSignoffsItemsChecklistRunItemIdGuidProof` | `recipe:attach-proof` |
| `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs` | Add / create / execute | `developerPostV1AppsModulesChecklistsSignoffsRuns` | `recipe:start-run` |
| `GET` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs/{checklistRunId}` | List / view | `developerGetV1AppsModulesChecklistsSignoffsRunsChecklistRunIdGuid` | `recipe:verify` |
| `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs/{checklistRunId}/submit` | Submit workflow | `developerPostV1AppsModulesChecklistsSignoffsRunsChecklistRunIdGuidSubmit` | `recipe:submit` |
| `GET` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates` | List / view | `developerGetV1AppsModulesChecklistsSignoffsTemplates` | `recipe:list-templates` |
| `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates` | Add / create / execute | `developerPostV1AppsModulesChecklistsSignoffsTemplates` | `recipe:create-template` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates/{checklistTemplateId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesChecklistsSignoffsTemplatesChecklistTemplateIdGuid` | `recipe:deactivate-template` |
| `GET` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates/{checklistTemplateId}` | List / view | `developerGetV1AppsModulesChecklistsSignoffsTemplatesChecklistTemplateIdGuid` | `recipe:open-template` |
| `PUT` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates/{checklistTemplateId}` | Edit / update / modify | `developerPutV1AppsModulesChecklistsSignoffsTemplatesChecklistTemplateIdGuid` | `recipe:update-template` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/files/upload` | File / attachment | `developerPostV1AppsModulesFilesUpload` | `recipe:upload-proof` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |

**Support Tickets (`support-tickets`)**

Readiness: **available** — the product's published recipe and composed surfaces are shipped in this kit.

Identity mode: `delegated-user`. Required recipe scopes: `modules.conversations.write`, `modules.universal-inbox.read`, `modules.universal-inbox.write`.

Composed first-class capability route sets: [conversations](#first-class-conversations), [dynamic-records](#first-class-dynamic-records), [knowledge-core](#first-class-knowledge-core), [record-relations](#first-class-record-relations), [universal-inbox](#first-class-universal-inbox)

Managed record day-to-day lifecycle:

| Managed record type | List | View | Add | Edit / modify | Remove | Favorite | Associate | Files / evidence | Activity |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `support-playbooks` | Yes — `GET` | Yes — `GET` | Yes — `POST` | Yes — `PUT` | Yes — `DELETE` (retire) | Yes — `PUT` on/off | Yes — `GET/PUT/DELETE` | Shared Files by authorized `recordId` | Yes — `GET` |

Derived/read-only surfaces do not duplicate destructive lifecycle actions:

| Surface | Native owner / return path | Why it is read-only here |
| --- | --- | --- |
| `support-ticket-attention` | `support-playbooks` | Universal Inbox projects the Conversation into ticket identity, attention, assignment, SLA and audited resolution state; it does not replace the source thread. |
| `support-customer-context` | `support-playbooks` | Related customer and business records remain independently secured native records with paths to their owning modules. |

Direct recipe/solution operations (16):

| Method | Route | Action | OpenAPI operationId | Origin |
| --- | --- | --- | --- | --- |
| `GET` | `/v1/apps/{saasAppId}/inbox/email-channels/ticketing` | Mailbox ticketing configuration | `developerGetV1AppsInboxEmailChannelsTicketing` | `recipe:list-email-channels` |
| `PUT` | `/v1/apps/{saasAppId}/inbox/email-channels/{channelConnectionId}/ticketing` | Mailbox ticketing configuration | `developerPutV1AppsInboxEmailChannelsChannelConnectionIdGuidTicketing` | `recipe:enable-ticketing` |
| `GET` | `/v1/apps/{saasAppId}/inbox/items` | List / view | `developerGetV1AppsInboxItems` | `recipe:list-tickets` |
| `GET` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}` | List / view | `developerGetV1AppsInboxItemsInboxItemIdGuid` | `recipe:open-ticket, recipe:verify` |
| `PUT` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}/human-state` | Human state / resolution | `developerPutV1AppsInboxItemsInboxItemIdGuidHumanState` | `recipe:resolve` |
| `POST` | `/v1/apps/{saasAppId}/modules/conversations/{recordId}/messages` | Message / reply | `developerPostV1AppsModulesConversationsRecordIdGuidMessages` | `recipe:reply` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | List / view | `developerGetV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | Add / create / execute | `developerPostV1AppsModulesDynamicModuleKey` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Delete / remove / deactivate | `developerDeleteV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | List / view | `developerGetV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | Edit / update / modify | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | Favorite / unfavorite | `developerPutV1AppsModulesDynamicModuleKeyRecordIdGuidFavorite` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | Activity / audit history | `developerGetV1AppsModulesRecordActivityRecordIdGuid` | `solution-manifest` |
| `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | Associate / remove relationship | `developerDeleteV1AppsModulesRecordGraphRelationsRecordRelationIdGuid` | `solution-manifest` |
| `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | Relationship graph | `developerGetV1AppsModulesRecordGraphRecordIdGuid` | `solution-manifest` |
| `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | Associate / add | `developerPutV1AppsModulesRecordGraphRecordIdGuidRelations` | `solution-manifest` |

Build This totals: **18 products**, **73 recipe step references**, and **76 unique direct recipe/solution routes** after adding manifest operations and removing duplicates.

## Interpretation constraints

- A route's presence is not permission. The server derives SaaS, tenant account, user, DataRole, location, and capabilities from verified identity.
- Route parameters such as `{saasAppId}`, `{recordId}`, or `{moduleKey}` are query targets, not authorization proof.
- Build This products are compositions. Their direct table is deliberately limited to routes explicitly named by generated recipes or solution manifests; their linked first-class modules provide the complete native route surface above.
- 'Every record' means every canonical record currently authorized for the caller. It never means tenant-wide disclosure, a relationship to a derived projection, or permission inherited through an edge.
- SQL procedures are not HTTP routes. Procedure joins remain in the machine-readable catalog and current database exports and are not duplicated here.
- This inventory is prospective technical documentation and does not reproduce private reasoning.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/api-map.html).

---
title: "Download and update the developer kit"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/choose-your-developer-kit.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Download and update the developer kit

Use one portable Developer Kit, then synchronize authorized account contracts inside its workspace.

## In brief

- **Developer kit:** 1.20.70
- **Account sync:** Generated live
- **Credentials:** External only

There is one canonical BuildWithHQ / API43 Developer Kit. Use it to build a website, trusted backend integration, or custom frontend for your SaaS, then run its account-sync tool when you need one account’s current pages, presentation, bindings, compatibility data, Lego catalogs and tenant route metadata in the same working directory.

## Download the current Developer Kit

The current release is **1.20.70**. [Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip). Download its [SHA-256 checksum](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip.sha256)  and verify the ZIP before extracting it. The public ZIP requires no tenant-admin permission to download. The archive includes OpenAPI, the SDK, React and Puck examples, API instructions, executable integration examples, and `tools/sync_account_overlay.py`. It contains no database credentials or API tokens. Calling protected APIs requires the appropriate key, identity, scopes and record-level permissions.

## Configure draft and live keys on your server

Create separate `bwk_draft_` and `bwk_live_` API clients, then store both credentials in a backend secret manager. Never put either credential in React, a `VITE_*` variable, page JSON, source control, or the downloaded ZIP. Existing kit tools read `BWHQ_API_CREDENTIAL` for the current operation: point it at the draft credential for unpublished page work and at the live credential only for reviewed live operations.

The account overlay contains tenant-specific information. Its sync uses a short-lived bearer from the real tenant sign-in flow and requires owner access or delegated Developer Kit and design capabilities; a long-lived app key alone does not authorize it. Set `BWHQ_TENANT_ORIGIN` and `BWHQ_TENANT_ACCESS_TOKEN`, then run `python tools/sync_account_overlay.py`. The tool verifies every manifest hash before atomically writing `account-overlay/` and never stores the token.

## Read version numbers as separate parts

Versions use `major.minor.patch`, not decimal numbers. Version `1.20.70` is later than `1.9` and `1.2`: minor version 20 comes after 9 and 2. Old release notes deliberately retain their original versions; they do not identify the latest download.

## Synchronize account-specific files

The generated account overlay contains the published capability and tenant-operation catalogs available to the authorized account, plus current pages, menus, bindings, compatibility data, ID-addressed Lego catalogs, React starters, and Contacts and Work Orders composite samples. Use the generated manifest and [API Map](api-map.html)  for the current inventory; the public kit and the live account overlay can reflect different release dates. Built-in capabilities are not hidden merely because they are not pinned to a menu. The direct **Admin → Developer kit** ZIP download remains available for compatibility and can be verified and expanded with the tool’s `--archive` option. See [Account administration](../end-user/account-administration.html)  for its contents and setup.

## Upgrade without losing your customizations

1. Read the [release notes](../changelog/index-notes.html)  and keep your existing project in source control.
2. Extract the new ZIP into a separate directory. Compare its OpenAPI, manifest, SDK, and examples with the version you use.
3. Merge relevant changes into your project; do not overwrite custom pages or configuration with sample files.
4. Run the checks documented in the kit and verify your integration against your test account before deployment.

The kit version identifies the downloadable package. API URLs still use their documented `/v1/` prefix; a new ZIP does not change the route version. See [API operating contracts](api-operating-contracts.html)  for contract fingerprints and compatibility.

## Start with your task

- [Make your first API request](quickstart.html).
- [Sign up customer organizations from your website](customer-organization-website-signup.html).
- [Customize React, CSS, and page design](../builder-guide/tailadmin-template-design-and-react-customization.html).
- [Receive webhooks and poll background jobs](webhook-receiver-and-background-jobs.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/choose-your-developer-kit.html).

---
title: "Developer platform overview"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/overview.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Developer platform overview

One permission-aware developer surface for records, connectors, events, AI, logs, MCP, and installed services.

## In brief

- **API origin:** https://api.buildwithhq.com
- **Current contract:** v1 · 422 operations
- **Core model:** One app-scoped security context

BuildWithHQ is designed so that an application is not only a visual SaaS product — it is also a **programmable backend**. The current v1 contract contains 422 operations across 340 paths for its published module and platform operations, including app identity, records, connectors, inbound endpoints, webhooks, installed services, AI, logs, and contract discovery.

| Surface | Use it for | Security boundary |
| --- | --- | --- |
| **REST APIs** | Read data, perform approved mutations, inspect schemas, and start operations from external software. | Authenticated identity + application scope + DataRole/location/permission checks. |
| **Webhooks** | Push application events to another system without polling. | Per-endpoint configuration, signed deliveries, retry/idempotency rules. |
| **Connectors** | Configure REST, GraphQL, OAuth, payment, inbound, and installed-service integrations. | Registered connector types, secret references, public HTTPS endpoints, and app-derived identity. |
| **AI and logs** | Ingest/search permitted records, manage rebuilds, and diagnose work by correlation ID. | Explicit scopes plus the same DataRole, location, and AI-read envelope as the app. |
| **MCP tools** | Let compatible AI clients discover and invoke approved application capabilities. | The same identity and permission envelope used by the API — MCP never bypasses it. |
| **Container services** | Add custom code when the visual platform or built-in actions are not enough. | Declared endpoints, input/output schemas, permission keys, egress policy, and invocation audit. |

## Documentation and executable contract

**support.buildwithhq.com** explains architecture, security rules, examples, troubleshooting, and recommended patterns. The generated OpenAPI document is the executable source for exact v1 paths, request schemas, response types, and operation IDs.

The production origin is **`https://api.buildwithhq.com`**. Before rollout, use the environment origin supplied by your BuildWithHQ administrator.

**Current Kit 1.20.70:** [fast rows, progressive loading and independently authorized exact counts](progressive-loading-and-counts.html)  let Contacts and Global Search browse up to 5,000 matches while a separate count reports every authorized match. This release also adds governed, exact-version [Skills discovery and GoClaw assignment](mcp-tools.html). See the [enterprise integration checklist](go-live-checklist.html)  for release, recovery and operational evidence requirements.

Note

An operation appearing in the generated v1 contract means the software contract exists. Availability at a particular origin still depends on that environment's deployment and your API client's scopes.

## The rule that matters most

Every surface passes through the same authorization boundary. A REST call, workflow step, MCP tool, or container endpoint cannot use its transport as a shortcut around application permissions. The server derives identity and application context, evaluates the requested capability, filters data, executes the approved operation, and records the action where required.

That is the central advantage of the BuildWithHQ developer model: **extend the application without building a parallel backend beside it.**

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/overview.html).

---
title: "Build a complete headless SaaS"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/headless-saas.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build a complete headless SaaS

Use published first-class module operations from your own React, mobile, desktop, or legacy interface without exposing an API credential to the browser.

## In brief

- **Public contract:** 422 operations
- **First-class modules:** 295 typed operations
- **Browser secrets:** None

A headless SaaS keeps your own interface while BuildWithHQ supplies the governed application backend. Developer Kit 1.20.70 exposes 295 promoted first-class module operations plus tenant account, user, role/location assignment, delegated-token, revocation, and DeepSeek Harness contracts. Build against the operations listed in that version without calling an internal tenant URL or connecting React to SQL. The native source catalog may contain later operations; their presence does not add them to an earlier Developer Kit.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Browse the OpenAPI contract](versioning-and-openapi.html) [Create an app credential](authentication.html)

## The production shape

```
Browser / mobile / desktop UI
        | your session + CSRF
        v
Your trusted server or narrow BFF
        | app-bound BuildWithHQ credential
        v
https://api.buildwithhq.com/v1/apps/{saasAppId}/...
        | server-derived app + user + DataRole + location scope
        v
Only the authorized, paginated result returns to your UI
```

The app credential is bound to one SaaS app. Your trusted server uses it to manage that app's tenant accounts and users, then exchanges its own user identity for a short-lived delegated token. Every module request executes the same secured service contract as the native application. The URL chooses a target; it never proves authority.

The kit-root `TENANT-PROVISIONING-AND-AUTHENTICATION.md` guide maps both supported provisioning paths. Signed-in SaaS builders can administer organizations in the Builder Console, while external servers use the published `bwk_live_` tenant-account and tenant-user operations. Builder product routes intentionally are not app-credential routes. Their separate `openapi/platform-owner.json` contract and `BuildWithHQPlatformClient` use the current verified Builder session.

## Connect a marketing-site signup

Your public pricing or signup page posts to your own authenticated, rate-limited backend-for-frontend. That server verifies the email and identity-provider subject, then calls `createTenantAccount` with its protected live-app credential. Never place a `bwk_live_` credential in browser JavaScript, a public form, or a mobile bundle, and never send a raw password to BuildWithHQ.

The one idempotent call creates the top-level customer organization, first owner, protected owner role, up to five initial DataRoles, and up to five initial Locations. The returned key-to-ID maps can seed later user assignments. Because this is the same routed AppAccount contract used by the consoles, the new customer appears immediately under the app's **Organizations** directory and the owner sees the in-SaaS **Account administration** area. Additional roles and locations can be added later through normal administration.

[Follow the complete customer-organization website signup guide.](customer-organization-website-signup.html)

## Act as the real end user

1. Create or resolve an AppAccount with your stable external organization ID.
2. Create a passwordless TenantUser and assign only DataRoles and Locations from that account.
3. Exchange the user's external subject for a 2–15 minute `bwu_live_` token from your trusted server.
4. Give only that short-lived token to that user's browser or mobile client. It cannot manage identities or mint tokens.
5. Revoke it explicitly or deactivate the user. Deactivation revokes every active delegated token for that app/account/user.

```
const account = await api.createTenantAccount({
  providerKey: "your-auth", externalAccountId: organization.id,
  accountName: organization.name, primaryEmail: organization.billingEmail,
  ownerExternalSubject: currentUser.id, ownerEmail: currentUser.email,
  ownerDisplayName: currentUser.name,
  dataRoles: [{
    key: "member", name: "Member", canRead: true,
    canReadRecords: true, permissionKeys: ["records.read"],
  }],
  locations: [{
    key: "head-office", name: "Head office",
    timeZone: "America/Los_Angeles",
  }],
});

const delegated = await api.exchangeDelegatedUserToken({
  providerKey: "your-auth", externalAccountId: organization.id,
  externalSubject: currentUser.id,
  scopes: ["modules.contacts.read", "modules.work-orders.read"],
  lifetimeMinutes: 10,
});
```

Note

Zero UserLocationXref rows is the explicit all-locations contract. Send locationScopeMode: "all" deliberately; for "selected", send at least one reviewed location ID. An omitted or empty update never silently expands access.

Management scopes are `tenant-accounts.read/write`, `tenant-users.read/write`, and `tenant-users.tokens.issue`. Identity mutations and token issuance are written to the SaaS immutable Logs database with API-client and represented-user context.

## Embed the published page body or the complete page

Create a delegated token with `runtime.pages.read`. `BuildWithHQRuntimeClient.getPageBody(pageKey)` returns the registered components and page body without BuildWithHQ menus or shell, so the existing product keeps its own navigation. Page design tokens are omitted by default and can be explicitly included. `getPageBootstrap(pageKey)` returns the complete shell, menus, components, and page when the host wants the full BuildWithHQ experience.

The kit carries one compiled local-only `packages/page-runtime` library. React and Puck install it through locked `file:` dependencies, so `npm ci` downloads their declared third-party dependencies without publishing BuildWithHQ code or requiring an npm organization. The library parses presentation data; the VB Developer API remains the secured HTTP data and authorization boundary.

For blocks with registered data sources, add `runtime.bindings.read` and call `resolveBindings` with at most 24 unique keys. All three calls require the short-lived `bwu_live_` credential and reuse the hosted runtime's user entitlement, DataRole, Location, record filtering, tenant routing, stored procedures, and audit.

## Copy the server-side TypeScript start

```
import { BuildWithHQModuleClient } from "./sdk/BuildWithHQConnector.js";

const api = new BuildWithHQModuleClient({
  saasAppId: process.env.BWHQ_SAAS_APP_ID!,
  credential: process.env.BWHQ_API_CREDENTIAL!,
});

export async function contactsPage(search = "") {
  return api.contactsList({ search, pageNumber: 1, pageSize: 50 });
}

export async function workOrdersPage() {
  return api.workOrdersList({ pageNumber: 1, pageSize: 50 });
}
```

Important

Run this code on a trusted server only. Never put BWHQ_API_CREDENTIAL in VITE_*, NEXT_PUBLIC_*, page JSON, browser storage, a mobile bundle, logs, prompts, or source control.

## What the 1.20.70 kit gives you

- **All 422 public operations** in semantically identical generated JSON and YAML OpenAPI files.
- **All 295 first-class module operations** as typed methods in `sdk/modules.generated.ts`, exported by `BuildWithHQConnector.ts`.
- **Exact required scopes on every operation** in `catalog/operations.json`, with module rate classes and aliases in the sanitized `catalog/module-surface.json`.
- **Complete request and response DTOs**, including lists, detail reads, writes, files, searches, ticketing, approvals, and module-specific state changes.
- **React presentation sources** for professional dashboards and native Builder pages, while leaving authentication and mutations on the trusted side of the boundary.
- **Machine-readable coverage** whose two SDK manifests must equal OpenAPI exactly before the ZIP builds.

## Builder names and API names are explicitly joined

`catalog/capabilities.json` records each Builder feature slug beside its Developer API module key, public base path, and scopes. For example, the Builder feature `record-relations` uses the `record-graph` API module, `knowledge-core` uses `knowledge-articles`, and `dynamic-records` is served below `/modules/dynamic`. The React gallery displays both identities so developers do not infer route names from marketing labels.

## Native Builder and headless are two views of the same system

Builders save registered React blocks and pages in BuildWithHQ; those blocks use a signed-in tenant session. Headless developers use the generated server SDK and paint the returned data in their own React or other client. Both paths reach the same module services and secured database contracts. A developer can prototype a presentation from the kit, then either publish it as a Builder component or host it in a headless interface—the identity mechanism changes, but the business contracts and server-side data scope do not.

## Go-live checks

1. Issue a least-privilege credential with only the module read/write scopes the server needs.
2. Keep list/search calls bounded and preserve server pagination; never download a tenant graph to render one row.
3. Handle 401, 403, 404, 409, 429, and 5xx distinctly and retain the correlation ID.
4. Test a valid record, a foreign-tenant record, and a random nonexistent ID. Foreign and nonexistent responses must remain indistinguishable.
5. Exercise optimistic concurrency, file scanning, retry/idempotency, empty states, mobile layout, keyboard access, and service recovery.
6. Generate clients from the checked-in OpenAPI version and pin the Developer Kit SHA-256 for the release.

A missing credential scope returns HTTP 403 with code `credential_scope_required`, safe message `The authenticated credential does not grant this operation.`, and a correlation ID. Checklist item updates and normal Contact updates declare HTTP 409 because they carry concurrency state. The Contacts favorite command is an idempotent boolean write without an expected revision, so its contract deliberately does not advertise 409.

Note

The repository implementation and local battle environment expose and test this contract. Availability at api.buildwithhq.com still depends on deploying that gateway build, database grants, TLS, routing, and credentials to the production environment.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/headless-saas.html).

---
title: "How customer organizations can signup from your website"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/customer-organization-website-signup.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How customer organizations can signup from your website

Connect your SaaS marketing-site signup and login to one governed BuildWithHQ customer organization and its first owner.

## In brief

- **Signup limit:** 5 DataRoles + 5 Locations
- **App secret in browser:** Never
- **Result:** One routed AppAccount

Your SaaS marketing site can offer its own branded signup and login while BuildWithHQ creates and secures the customer organization behind it. The customer sees your website and identity provider. Your trusted backend makes the app-bound BuildWithHQ calls.

## What one signup creates

- One top-level customer organization (`AppAccount`) inside the selected SaaS app.
- The first active tenant user as the protected account owner.
- The account-local owner User Type and Account Owner DataRole.
- Up to five additional initial DataRoles and up to five initial Locations.
- Stable external organization/user identity links for idempotent retries and later login.

The organization is immediately visible under **SaaS Apps > your app > Organizations** in the Builder administration area. The owner sees the same organization in the SaaS **Account administration** workspace. Both read the same routed AppAccount; no import or synchronization job is involved.

## 1. Create the server credential

Create a live-app API client for this SaaS app with `tenant-accounts.write` and `tenant-users.tokens.issue`. Add `tenant-accounts.read` only when the backend must resolve the organization separately. Keep the resulting `bwk_live_` value in a server secret store.

Important

Never put a bwk_live_ credential in HTML, React/Vite public environment variables, browser storage, a mobile bundle, page JSON, logs, or source control. The public form posts to your server, not directly to BuildWithHQ.

## 2. Authenticate and verify the public signup

Use your identity provider for email verification, password/passkey handling, MFA, recovery, bot defense, rate limiting, signup consent, and session cookies. BuildWithHQ accepts the provider's stable organization ID and stable user subject; it does not accept or store the customer's raw password on this route.

```
Marketing signup form
    | your HTTPS session + CSRF + bot/rate controls
    v
Your trusted signup BFF
    | verifies email and identity-provider claims
    | uses server-only bwk_live_ credential
    v
POST /v1/apps/{saasAppId}/accounts
    | atomic routed transaction
    v
Organization + owner + initial roles/locations
```

## 3. Post the verified signup

```
import { BuildWithHQConnector } from "@your-server/buildwithhq-connector";

const api = new BuildWithHQConnector({
  saasAppId: process.env.BWHQ_SAAS_APP_ID!,
  credential: process.env.BWHQ_API_CREDENTIAL!,
});

const account = await api.createTenantAccount({
  providerKey: "marketing-auth",
  externalAccountId: verifiedOrganization.id,
  accountName: verifiedOrganization.name,
  primaryEmail: verifiedOwner.email,
  ownerExternalSubject: verifiedOwner.subject,
  ownerEmail: verifiedOwner.email,
  ownerDisplayName: verifiedOwner.displayName,
  dataRoles: [
    { key: "member", name: "Member", canRead: true, canReadRecords: true,
       permissionKeys: ["records.read"] },
    { key: "manager", name: "Manager", canRead: true, canCreate: true,
       canEdit: true, canReadRecords: true, permissionKeys: ["records.read"] },
  ],
  locations: [
    { key: "head-office", name: "Head office", timeZone: "America/Los_Angeles" },
  ],
});
```

Each role/location `key` is a caller-defined key used only to correlate the response. The response returns its new `dataRoleId` or `locationId`. Send no more than five entries in either array. Add or edit additional roles and locations later through Builder, in-SaaS administration, or the app-scoped Developer API.

## 4. Handle retries safely

The operation is idempotent for `providerKey + externalAccountId`. The first creation and a matching replay both return HTTP `201`; inspect `created` (`true` for creation and `false` for replay). Both responses include the persisted `accountName`, `primaryEmail`, `status`, `createdUtc`, and `updatedUtc`. A different owner subject for that external organization returns HTTP `409` with the shared safe error envelope. If a dependency fails after submission, look up the external organization ID before retrying because the create may already have committed. Do not generate a new external organization ID for every retry.

## 5. Log the owner in

After your identity provider authenticates the person, your BFF exchanges the verified external organization ID and user subject for a two-to-fifteen-minute delegated token:

```
const delegated = await api.exchangeDelegatedUserToken({
  providerKey: "marketing-auth",
  externalAccountId: verifiedOrganization.id,
  externalSubject: verifiedOwner.subject,
  scopes: ["modules.contacts.read", "modules.work-orders.read"],
  lifetimeMinutes: 10,
});

// Return only delegated.accessToken to this authenticated browser session.
```

The browser uses that `bwu_live_` token for the allowed runtime/module routes. It cannot create organizations, manage users, or mint another token. Each call rechecks the active user, DataRoles, Locations, permissions, and record visibility.

## 6. Verify both administration views

1. In Builder administration, open the SaaS app and select **Organizations**. Confirm the organization, owner, user count, DataRole count, Location count, and status.
2. Log in as the new owner and open **Account administration** inside the SaaS. Confirm People, Access, Security, Audit, Exports, Developer, and permitted presentation sections.
3. Add another user with a distinct verified external subject and assign only IDs returned for this AppAccount.
4. Test duplicate signup, a conflicting owner subject, six roles, six locations, a foreign app ID, missing scopes, and a deactivated user. Each must fail or replay exactly as documented without partial rows.

## 7. Manage the organization after signup

The trusted backend can search its organizations, update identity and status, maintain DataRoles and Locations, administer invitations, and transfer ownership. Every mutation is app-bound and revision-fenced.

```
const organizations = await api.listTenantAccounts({ search: "Acme", pageSize: 25 });
const org = await api.getTenantAccountAdmin(organizations.organizations[0].appAccountId);
await api.updateTenantAccount(org.appAccountId, {
  expectedUpdatedUtc: org.updatedUtc,
  accountName: "Acme Field Service",
  primaryEmail: "billing@acme.example",
  status: "Active",
});
const invitation = await api.createTenantInvitation(org.appAccountId, {
  email: "new.user@acme.example", displayName: "New User", userTypeKey: "member",
  dataRoleIds: [org.dataRoles[0].dataRoleId], locationScopeMode: "all", locationIds: [],
});
const acceptUrl = `https://customer.example/accept-invitation#token=${encodeURIComponent(invitation.acceptanceToken)}`;
```

Deliver the once-only token from your backend and never log it. Resend rotates it; revoke invalidates it. The recipient supplies a password only to the hosted tenant authentication route. Ownership transfer verifies an active, independently sign-in-capable target and revokes the previous owner's sessions.

## Credential boundary

| Caller | Credential | Allowed work |
| --- | --- | --- |
| Public browser | Your session; later a short-lived `bwu_live_` | Submit signup to your BFF and use delegated module/runtime routes. |
| Signup/login BFF | Server-only `bwk_live_` | Create/reconcile organizations and exchange verified external users. |
| Builder Console | Signed-in BuildWithHQ Builder session | List and administer every organization belonging to the owned SaaS app. |

Note

The API credential has no database password, table access, or DDL rights. The gateway binds it to one SaaS app and the database role can execute only allow-listed procedures. Client-supplied IDs select targets; they never establish authority.

For the full contract and copyable server starter, download Developer Kit 1.20.70 and read `TENANT-PROVISIONING-AND-AUTHENTICATION.md` plus `HEADLESS-USER-DELEGATION.md`.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/customer-organization-website-signup.html).

---
title: "Build This API recipes"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/build-this-api-recipes.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Build This API recipes

Eighteen complete, contract-backed API slices for BuildWithHQ and API43 product concepts.

## In brief

- **Recipes:** 18
- **Contract source:** Generated OpenAPI
- **Placeholder routes:** None

These recipes turn each Build This concept into an ordered API slice. Every method, path, authentication label, accepted credential class, scope, parameter, request schema, response status, and SDK method is generated from the current public contract. Authentication is one of `public`, `draft-app`, `live-app`, or `live-or-delegated`. The release build regenerates the recipe JSON and fails when its operation hash or per-step authentication differs from the catalog.

[Download all recipes](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [OpenAPI and versioning](versioning-and-openapi.html) [Delegated-user security](headless-saas.html)

## How to use a recipe

1. Choose the product slice and grant a backend credential only its listed scopes.
2. Use real identifiers returned by prior steps or selected from real app configuration; the recipes contain no sample GUIDs.
3. Use the app credential only for account and user administration. Exchange it for a short-lived user token before performing end-user work.
4. Resolve each step's request body from the named OpenAPI schema. Generated clients receive the same shape.
5. Carry correlation IDs end to end and run all four release assertions.

A credential missing a listed scope must receive HTTP 403 with `credential_scope_required`. A delegated user outside the record envelope must receive the module's non-disclosing 403/404 response, and no mutation may occur.

```
import { BuildWithHQModuleClient } from "./sdk/BuildWithHQConnector.js";

const api = new BuildWithHQModuleClient({
  saasAppId: process.env.BWHQ_SAAS_APP_ID!,
  credential: delegatedUserToken,
});

// Choose the exact typed method listed below. Values come from the signed-in
// user's permitted selection or a prior response, never from a sample tenant.
const result = await api.workOrdersGet({ recordId });
```

Important

The examples describe executable API flows; they do not grant permission. A route parameter identifies a target and never proves that the caller may read or mutate it.

## CrewOS

Coordinate AI operators, inspect governed work, and approve a proposed action with replayable evidence.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.goclaw.read` `modules.goclaw.write` `modules.record-graph.read` `modules.universal-inbox.read`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | Inspect work waiting for the signed-in user's approval. | `GET` | `/v1/apps/{saasAppId}/goclaw/approvals` | `modules.goclaw.read` | `goClawApprovalsGet` |
| **2** | Load the permitted relationship graph behind the proposed work. | `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | `modules.record-graph.read` | `recordGraphGet` |
| **3** | Approve the reviewed suggestion batch through the governed action boundary. | `POST` | `/v1/apps/{saasAppId}/goclaw/approvals/{suggestionBatchId}/approve` | `modules.goclaw.write` | `goClawApprovalsApprove` |
| **4** | Verify the resulting human attention state in Universal Inbox. | `GET` | `/v1/apps/{saasAppId}/inbox/items` | `modules.universal-inbox.read` | `universalInboxGetItems` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete CrewOS implementation guide](../how-to-do-this/crewos.html)

## SignalIQ

Turn secured account context into explainable signals and a reviewed action queue.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.ai-insights.read` `modules.ai-insights.write` `modules.contacts.read` `modules.record-graph.read`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | Find the permitted account or contact record. | `GET` | `/v1/apps/{saasAppId}/modules/contacts` | `modules.contacts.read` | `contactsList` |
| **2** | Load connected records without crossing the user's DataRole or location scope. | `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | `modules.record-graph.read` | `recordGraphGet` |
| **3** | Read the user's ranked AI insight queue. | `GET` | `/v1/apps/{saasAppId}/modules/ai-insights` | `modules.ai-insights.read` | `aiInsightsList` |
| **4** | Open the evidence and explanation for one insight. | `GET` | `/v1/apps/{saasAppId}/modules/ai-insights/{insightId}` | `modules.ai-insights.read` | `aiInsightsGet` |
| **5** | Record the user's reviewed disposition of the insight. | `PUT` | `/v1/apps/{saasAppId}/modules/ai-insights/{insightId}/state` | `modules.ai-insights.write` | `aiInsightsSetState` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete SignalIQ implementation guide](../how-to-do-this/signaliq.html)

## Resolve

Work a support request from a scoped inbox item through policy evidence and a human-controlled resolution.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.conversations.write` `modules.knowledge-articles.read` `modules.universal-inbox.read` `modules.universal-inbox.write`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | List the signed-in support user's permitted inbox work. | `GET` | `/v1/apps/{saasAppId}/inbox/items` | `modules.universal-inbox.read` | `universalInboxGetItems` |
| **2** | Open one inbox item and its ticket context. | `GET` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}` | `modules.universal-inbox.read` | `universalInboxGetItem` |
| **3** | Search the secured knowledge core for relevant policy. | `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core` | `modules.knowledge-articles.read` | `knowledgeCoreList` |
| **4** | Post the reviewed response into the native conversation. | `POST` | `/v1/apps/{saasAppId}/modules/conversations/{recordId}/messages` | `modules.conversations.write` | `conversationsReply` |
| **5** | Update the human-owned inbox state after resolution. | `PUT` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}/human-state` | `modules.universal-inbox.write` | `universalInboxUpdateHumanState` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete Resolve implementation guide](../how-to-do-this/resolve.html)

## LaunchPilot

Create a governed campaign record, attach assets, and route material actions through approval.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.dynamic-records.read` `modules.dynamic-records.write` `modules.files.write` `modules.goclaw.read`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | Read the registered campaign module schema before writing. | `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/schema` | `modules.dynamic-records.read` | `dynamicModulesSchema` |
| **2** | Create a campaign record through the reviewed dynamic-module contract. | `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | `modules.dynamic-records.write` | `dynamicModulesCreate` |
| **3** | Upload an approved campaign asset through the secured file path. | `POST` | `/v1/apps/{saasAppId}/modules/files/upload` | `modules.files.write` | `filesUpload` |
| **4** | List material AI actions awaiting human approval. | `GET` | `/v1/apps/{saasAppId}/goclaw/approvals` | `modules.goclaw.read` | `goClawApprovalsGet` |
| **5** | Read the created campaign in the same delegated-user scope. | `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}` | `modules.dynamic-records.read` | `dynamicModulesGet` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete LaunchPilot implementation guide](../how-to-do-this/launchpilot.html)

## Northstar

Build evidence-backed executive signals from secured search, insight, graph, and activity contracts.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.ai-insights.read` `modules.ai-insights.write` `modules.global-search.read` `modules.record-activity.read` `modules.record-graph.read`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | Search only records visible to the executive persona. | `GET` | `/v1/apps/{saasAppId}/modules/global-search` | `modules.global-search.read` | `globalSearchSearch` |
| **2** | Load material AI insights for the same identity. | `GET` | `/v1/apps/{saasAppId}/modules/ai-insights` | `modules.ai-insights.read` | `aiInsightsList` |
| **3** | Open the connected evidence graph for a selected signal. | `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | `modules.record-graph.read` | `recordGraphGet` |
| **4** | Load replayable activity for the selected record. | `GET` | `/v1/apps/{saasAppId}/modules/record-activity/{recordId}` | `modules.record-activity.read` | `recordActivityGet` |
| **5** | Persist the executive's reviewed insight state. | `PUT` | `/v1/apps/{saasAppId}/modules/ai-insights/{insightId}/state` | `modules.ai-insights.write` | `aiInsightsSetState` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete Northstar implementation guide](../how-to-do-this/northstar.html)

## TeamBox

Normalize team communications into a shared, permission-aware queue with native replies.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.conversations.read` `modules.conversations.write` `modules.universal-inbox.read` `modules.universal-inbox.write`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | List permitted inbox work across connected channels. | `GET` | `/v1/apps/{saasAppId}/inbox/items` | `modules.universal-inbox.read` | `universalInboxGetItems` |
| **2** | Open one normalized inbox item. | `GET` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}` | `modules.universal-inbox.read` | `universalInboxGetItem` |
| **3** | Load the native conversation that remains the source record. | `GET` | `/v1/apps/{saasAppId}/modules/conversations/{recordId}` | `modules.conversations.read` | `conversationsGet` |
| **4** | Post a team reply through the conversation contract. | `POST` | `/v1/apps/{saasAppId}/modules/conversations/{recordId}/messages` | `modules.conversations.write` | `conversationsReply` |
| **5** | Update the human attention state without changing source ownership. | `PUT` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}/human-state` | `modules.universal-inbox.write` | `universalInboxUpdateHumanState` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete TeamBox implementation guide](../how-to-do-this/teambox.html)

## RelateEverything

Create a CRM record, connect it to permitted business context, and verify the secured graph.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.contacts.write` `modules.global-search.read` `modules.record-graph.read` `modules.record-graph.write`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | Create a contact through the first-class Contacts contract. | `POST` | `/v1/apps/{saasAppId}/modules/contacts` | `modules.contacts.write` | `contactsCreate` |
| **2** | Create a reviewed relation from the new contact to another permitted record. | `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | `modules.record-graph.write` | `recordGraphAddRelation` |
| **3** | Read the contact's secured relationship graph. | `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | `modules.record-graph.read` | `recordGraphGet` |
| **4** | Verify the contact is discoverable through global secured search. | `GET` | `/v1/apps/{saasAppId}/modules/global-search` | `modules.global-search.read` | `globalSearchSearch` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete RelateEverything implementation guide](../how-to-do-this/relateeverything.html)

## CustomerPortal

Provision a portal identity and let that user work only with explicitly shared conversations, files, and approvals.

**Identity:** `app-credential-then-delegated-user`
**Least-privilege scopes:** `modules.conversations.read` `modules.files.read` `tenant-accounts.write` `tenant-users.read` `tenant-users.tokens.issue` `tenant-users.write`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | Create or reconcile the customer's tenant account from the ISV backend. | `POST` | `/v1/apps/{saasAppId}/accounts` | `tenant-accounts.write` | `createTenantAccount` |
| **2** | Resolve assignable user types, DataRoles, and locations for that account. | `GET` | `/v1/apps/{saasAppId}/accounts/{appAccountId}/security-catalog` | `tenant-users.read` | `getTenantSecurityCatalog` |
| **3** | Create the external user mapping with reviewed assignments. | `POST` | `/v1/apps/{saasAppId}/accounts/{appAccountId}/users` | `tenant-users.write` | `createTenantUser` |
| **4** | Exchange the app credential for a short-lived delegated-user token. | `POST` | `/v1/apps/{saasAppId}/user-token-exchanges` | `tenant-users.tokens.issue` | `exchangeDelegatedUserToken` |
| **5** | Use the delegated token to list only files visible to the portal user. | `GET` | `/v1/apps/{saasAppId}/modules/files` | `modules.files.read` | `filesList` |
| **6** | Use the same identity to list shared conversations. | `GET` | `/v1/apps/{saasAppId}/modules/conversations` | `modules.conversations.read` | `conversationsList` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete CustomerPortal implementation guide](../how-to-do-this/customerportal.html)

## CompanyIQ

Publish governed knowledge, connect it to business records, and retrieve permission-aware AI evidence.

**Identity:** `delegated-user`
**Least-privilege scopes:** `ai.read` `ai.write` `modules.knowledge-articles.write` `modules.record-graph.write`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | Create a revisioned knowledge record. | `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core` | `modules.knowledge-articles.write` | `knowledgeCoreCreate` |
| **2** | Publish the reviewed revision through the knowledge lifecycle. | `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/publish` | `modules.knowledge-articles.write` | `knowledgeCorePublish` |
| **3** | Attach the knowledge record to permitted business context. | `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/knowledge` | `modules.record-graph.write` | `recordGraphLinkKnowledge` |
| **4** | Queue the permitted record for AI ingestion. | `POST` | `/v1/apps/{saasAppId}/ai/sources/records/{recordId}/ingest` | `ai.write` | `ingestAiRecord` |
| **5** | Retrieve secured AI evidence using the delegated-user context. | `POST` | `/v1/apps/{saasAppId}/ai/search` | `ai.read` | `searchAi` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete CompanyIQ implementation guide](../how-to-do-this/companyiq.html)

## OpsAtlas

Operate revisioned policy knowledge with owners, reviews, questions, gaps, and health evidence.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.knowledge-articles.read` `modules.knowledge-articles.write`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | Create an owned operational knowledge record. | `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core` | `modules.knowledge-articles.write` | `knowledgeCoreCreate` |
| **2** | Assign a permitted knowledge owner. | `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/owners` | `modules.knowledge-articles.write` | `knowledgeCoreSetOwner` |
| **3** | Publish the reviewed revision. | `POST` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/publish` | `modules.knowledge-articles.write` | `knowledgeCorePublish` |
| **4** | Measure the current knowledge health contract. | `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/health` | `modules.knowledge-articles.read` | `knowledgeCoreHealth` |
| **5** | List permission-aware knowledge gaps requiring work. | `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/gaps` | `modules.knowledge-articles.read` | `knowledgeCoreGaps` |
| **6** | Read the immutable revision sequence for the record. | `GET` | `/v1/apps/{saasAppId}/modules/knowledge-core/{recordId}/revisions` | `modules.knowledge-articles.read` | `knowledgeCoreRevisions` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete OpsAtlas implementation guide](../how-to-do-this/opsatlas.html)

## Headless SaaS DB

Provision tenant identities and operate custom records from any frontend without exposing SQL or infrastructure routing.

**Identity:** `app-credential-then-delegated-user`
**Least-privilege scopes:** `modules.dynamic-records.write` `modules.record-graph.read` `modules.record-graph.write` `records.read` `records.write` `tenant-accounts.write` `tenant-users.tokens.issue` `tenant-users.write` `webhooks.write`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | Create or reconcile the external tenant account. | `POST` | `/v1/apps/{saasAppId}/accounts` | `tenant-accounts.write` | `createTenantAccount` |
| **2** | Map the external end user to a real TenantUser. | `POST` | `/v1/apps/{saasAppId}/accounts/{appAccountId}/users` | `tenant-users.write` | `createTenantUser` |
| **3** | Issue a short-lived delegated-user token for browser or mobile use. | `POST` | `/v1/apps/{saasAppId}/user-token-exchanges` | `tenant-users.tokens.issue` | `exchangeDelegatedUserToken` |
| **4** | Read the registered custom object's contract. | `GET` | `/v1/apps/{saasAppId}/objects/{objectKey}/schema` | `records.read` | `getSchema` |
| **5** | Create a record under server-derived user scope. | `POST` | `/v1/apps/{saasAppId}/objects/{objectKey}/records` | `records.write` | `createRecord` |
| **6** | Read the new record as the same delegated user. | `GET` | `/v1/apps/{saasAppId}/objects/{objectKey}/records/{recordId}` | `records.read` | `getRecord` |
| **7** | Update typed custom fields through the reviewed record contract. | `PATCH` | `/v1/apps/{saasAppId}/objects/{objectKey}/records/{recordId}` | `records.write` | `updateRecord` |
| **8** | Add or remove the record from the represented user's Favorites. | `PUT` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/{recordId}/favorite` | `modules.dynamic-records.write` | `dynamicModulesFavorite` |
| **9** | Associate the record with another permitted record without granting access. | `PUT` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}/relations` | `modules.record-graph.write` | `recordGraphAddRelation` |
| **10** | Read the independently authorized relationship graph. | `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | `modules.record-graph.read` | `recordGraphGet` |
| **11** | Remove the reviewed association by its relation identity. | `DELETE` | `/v1/apps/{saasAppId}/modules/record-graph/relations/{recordRelationId}` | `modules.record-graph.write` | `recordGraphRemoveRelation` |
| **12** | Create a signed outbound record-event subscription. | `POST` | `/v1/apps/{saasAppId}/webhooks` | `webhooks.write` | `createWebhookSubscription` |
| **13** | Deactivate the webhook through its native lifecycle. | `PUT` | `/v1/apps/{saasAppId}/webhooks/{subscriptionId}` | `webhooks.write` | `updateWebhookSubscription` |
| **14** | Archive or soft-delete the record through the current removal contract. | `DELETE` | `/v1/apps/{saasAppId}/objects/{objectKey}/records/{recordId}` | `records.write` | `deleteRecord` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete Headless SaaS DB implementation guide](../how-to-do-this/headless-saas-db.html)

## CaseFlow

Create a controlled case, collect proof, execute checklist stages, and surface approval work.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.checklists-signoffs.write` `modules.dynamic-records.read` `modules.dynamic-records.write` `modules.files.write` `modules.universal-inbox.read`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | Read the registered case module schema. | `GET` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}/schema` | `modules.dynamic-records.read` | `dynamicModulesSchema` |
| **2** | Create the case through the reviewed dynamic module. | `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | `modules.dynamic-records.write` | `dynamicModulesCreate` |
| **3** | Start the configured stage checklist against the case record. | `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs` | `modules.checklists-signoffs.write` | `checklistsStartRun` |
| **4** | Upload case evidence through Files. | `POST` | `/v1/apps/{saasAppId}/modules/files/upload` | `modules.files.write` | `filesUpload` |
| **5** | Submit completed stage work for governed signoff. | `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs/{checklistRunId}/submit` | `modules.checklists-signoffs.write` | `checklistsSubmit` |
| **6** | Verify the resulting approval work in Universal Inbox. | `GET` | `/v1/apps/{saasAppId}/inbox/items` | `modules.universal-inbox.read` | `universalInboxGetItems` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete CaseFlow implementation guide](../how-to-do-this/caseflow.html)

## AssetOps

Connect customers, assets, work orders, inspections, and field evidence under one secured graph.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.checklists-signoffs.write` `modules.dynamic-records.write` `modules.files.write` `modules.record-graph.read` `modules.work-orders.write`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | Create an asset in its registered dynamic module. | `POST` | `/v1/apps/{saasAppId}/modules/dynamic/{moduleKey}` | `modules.dynamic-records.write` | `dynamicModulesCreate` |
| **2** | Create work against the permitted asset or location context. | `POST` | `/v1/apps/{saasAppId}/modules/work-orders` | `modules.work-orders.write` | `workOrdersCreate` |
| **3** | Start the asset inspection checklist. | `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs` | `modules.checklists-signoffs.write` | `checklistsStartRun` |
| **4** | Upload inspection evidence through Files. | `POST` | `/v1/apps/{saasAppId}/modules/files/upload` | `modules.files.write` | `filesUpload` |
| **5** | Verify that the user can see the resulting connected context. | `GET` | `/v1/apps/{saasAppId}/modules/record-graph/{recordId}` | `modules.record-graph.read` | `recordGraphGet` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete AssetOps implementation guide](../how-to-do-this/assetops.html)

## ActiveWorkplace

Pin a permitted record graph as a collaborative workplace with participants, activity, stale-work controls, and playback.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.active-workplace.read` `modules.active-workplace.write`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | Create a workplace rooted at a permitted record. | `POST` | `/v1/apps/{saasAppId}/modules/active-workplace` | `modules.active-workplace.write` | `activeWorkplaceCreate` |
| **2** | Load the scoped participant catalog. | `GET` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/participants/catalog` | `modules.active-workplace.read` | `activeWorkplaceParticipantCatalog` |
| **3** | Add a permitted person or worker. | `POST` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/participants` | `modules.active-workplace.write` | `activeWorkplaceAddParticipant` |
| **4** | Record collaborative activity through the workplace contract. | `POST` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/activity` | `modules.active-workplace.write` | `activeWorkplaceRecordActivity` |
| **5** | Refresh the permitted recursive graph snapshot. | `POST` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/graph/refresh` | `modules.active-workplace.write` | `activeWorkplaceRefreshGraph` |
| **6** | Replay the workplace history. | `GET` | `/v1/apps/{saasAppId}/modules/active-workplace/{activeWorkplaceId}/playback` | `modules.active-workplace.read` | `activeWorkplacePlayback` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete ActiveWorkplace implementation guide](../how-to-do-this/activeworkplace.html)

## FieldService

Move a field job from customer intake through assignment, schedule, evidence, and completion.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.calendar.write` `modules.checklists-signoffs.write` `modules.contacts.read` `modules.work-orders.write`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | Find the permitted customer contact. | `GET` | `/v1/apps/{saasAppId}/modules/contacts` | `modules.contacts.read` | `contactsList` |
| **2** | Create the field work order. | `POST` | `/v1/apps/{saasAppId}/modules/work-orders` | `modules.work-orders.write` | `workOrdersCreate` |
| **3** | Assign a permitted technician and role. | `PUT` | `/v1/apps/{saasAppId}/modules/work-orders/{recordId}/assignment` | `modules.work-orders.write` | `workOrdersAssign` |
| **4** | Create the scheduled field appointment. | `POST` | `/v1/apps/{saasAppId}/modules/calendar` | `modules.calendar.write` | `calendarCreate` |
| **5** | Start the configured completion checklist. | `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs` | `modules.checklists-signoffs.write` | `checklistsStartRun` |
| **6** | Advance work status through the reviewed transition contract. | `PUT` | `/v1/apps/{saasAppId}/modules/work-orders/{recordId}/status` | `modules.work-orders.write` | `workOrdersStatus` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete FieldService implementation guide](../how-to-do-this/fieldservice.html)

## Reservations

Publish bookable capacity, create a purchase, and operate its status and follow-up lifecycle.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.reservations.read` `modules.reservations.write`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | Create or update a bookable product and capacity contract. | `POST` | `/v1/apps/{saasAppId}/modules/reservations/products` | `modules.reservations.write` | `reservationsUpsertProduct` |
| **2** | Read products visible to the delegated user. | `GET` | `/v1/apps/{saasAppId}/modules/reservations/products` | `modules.reservations.read` | `reservationsListProducts` |
| **3** | Create a reservation through the reviewed purchase boundary. | `POST` | `/v1/apps/{saasAppId}/modules/reservations/purchase` | `modules.reservations.write` | `reservationsPurchase` |
| **4** | Read the resulting reservation. | `GET` | `/v1/apps/{saasAppId}/modules/reservations/{recordId}` | `modules.reservations.read` | `reservationsGet` |
| **5** | Advance the reservation through a reviewed status transition. | `PUT` | `/v1/apps/{saasAppId}/modules/reservations/{recordId}/status` | `modules.reservations.write` | `reservationsSetStatus` |
| **6** | Record pre- or post-service follow-up state. | `PUT` | `/v1/apps/{saasAppId}/modules/reservations/{recordId}/followups` | `modules.reservations.write` | `reservationsUpdateFollowup` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete Reservations implementation guide](../how-to-do-this/reservations.html)

## Checkoff & Approval

Attach a reusable checklist to work, collect document or photo proof per item, and submit it for governed signoff.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.checklists-signoffs.read` `modules.checklists-signoffs.write` `modules.files.write`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | List the reusable templates visible to the delegated tenant identity. | `GET` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates` | `modules.checklists-signoffs.read` | `checklistsListTemplates` |
| **2** | Create a reusable checklist template with no more than 1,000 items. | `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates` | `modules.checklists-signoffs.write` | `checklistsCreateTemplate` |
| **3** | Read the complete ordered template and current concurrency value. | `GET` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates/{checklistTemplateId}` | `modules.checklists-signoffs.read` | `checklistsGetTemplate` |
| **4** | Revise instructions and proof rules against ExpectedUpdatedUtc. | `PUT` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates/{checklistTemplateId}` | `modules.checklists-signoffs.write` | `checklistsUpdateTemplate` |
| **5** | Attach a checklist run to a permitted record. | `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs` | `modules.checklists-signoffs.write` | `checklistsStartRun` |
| **6** | Complete an item using its current revision fence. | `PUT` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/items/{checklistRunItemId}` | `modules.checklists-signoffs.write` | `checklistsUpdateItem` |
| **7** | Upload a document or photo through Files. | `POST` | `/v1/apps/{saasAppId}/modules/files/upload` | `modules.files.write` | `filesUpload` |
| **8** | Attach the uploaded file as item evidence. | `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/items/{checklistRunItemId}/proof` | `modules.checklists-signoffs.write` | `checklistsAttachProof` |
| **9** | Submit the revision-fenced run for human approval. | `POST` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs/{checklistRunId}/submit` | `modules.checklists-signoffs.write` | `checklistsSubmit` |
| **10** | Reload the run and evidence after submission. | `GET` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/runs/{checklistRunId}` | `modules.checklists-signoffs.read` | `checklistsGetRun` |
| **11** | Deactivate the template while preserving every historical run snapshot. | `DELETE` | `/v1/apps/{saasAppId}/modules/checklists-signoffs/templates/{checklistTemplateId}` | `modules.checklists-signoffs.write` | `checklistsRemoveTemplate` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete Checkoff & Approval implementation guide](../how-to-do-this/checkoff-approval.html)

## Support Tickets

Enable ticketing on a selected email address and operate stable ticket work through Universal Inbox.

**Identity:** `delegated-user`
**Least-privilege scopes:** `modules.conversations.write` `modules.universal-inbox.read` `modules.universal-inbox.write`

| # | Purpose | Verb | Path | Scope | SDK / operation |
| --- | --- | --- | --- | --- | --- |
| **1** | List configured email channels and their ticketing state. | `GET` | `/v1/apps/{saasAppId}/inbox/email-channels/ticketing` | `modules.universal-inbox.read` | `universalInboxGetEmailTicketing` |
| **2** | Enable ticketing on the selected channel through the reviewed configuration contract. | `PUT` | `/v1/apps/{saasAppId}/inbox/email-channels/{channelConnectionId}/ticketing` | `modules.universal-inbox.write` | `universalInboxSetEmailTicketing` |
| **3** | List permitted inbox items using the ticket filters published by the contract. | `GET` | `/v1/apps/{saasAppId}/inbox/items` | `modules.universal-inbox.read` | `universalInboxGetItems` |
| **4** | Open the durable ticket and its stable identity. | `GET` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}` | `modules.universal-inbox.read` | `universalInboxGetItem` |
| **5** | Post the reviewed response to the native conversation. | `POST` | `/v1/apps/{saasAppId}/modules/conversations/{recordId}/messages` | `modules.conversations.write` | `conversationsReply` |
| **6** | Move the ticket's human state through the resolution lifecycle. | `PUT` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}/human-state` | `modules.universal-inbox.write` | `universalInboxUpdateHumanState` |
| **7** | Reload the ticket to verify its final state and correlation evidence. | `GET` | `/v1/apps/{saasAppId}/inbox/items/{inboxItemId}` | `modules.universal-inbox.read` | `universalInboxGetItem` |

### Release assertions

- Repeat every user-scoped read with a user from another AppAccount and require no protected data.
- Remove one required scope and require a stable 403 response without performing the mutation.
- Retry a revision-fenced or idempotent mutation and verify no duplicate business effect.
- Persist and inspect the returned correlation ID for every rejected or failed request.

[Read the complete Support Tickets implementation guide](../how-to-do-this/support-tickets.html)

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/build-this-api-recipes.html).

---
title: "Developer API quickstart"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/quickstart.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Developer API quickstart

Create an app-scoped credential, verify its identity, make a first record request, and retain correlation evidence.

## In brief

- **Time:** About 10 minutes
- **First check:** Auth context
- **Secret storage:** Environment or protected file

This path proves the three things every integration needs before it performs real work: the API origin is reachable, the credential is bound to the intended SaaS app, and the requested scope is authorized.

## 1. Create an API client

In the Developer Console, open the SaaS app and create an API client with only the scopes needed by the integration. Copy the one-time credential into a secret manager or protected environment variable. BuildWithHQ does not show the raw value again.

```
# PowerShell
$env:BWHQ_API_CREDENTIAL = "bwk_live_..."

# Bash
export BWHQ_API_CREDENTIAL="bwk_live_..."
```

## 2. Verify app-bound identity

```
curl --fail-with-body   -H "Authorization: Bearer $BWHQ_API_CREDENTIAL"   https://api.buildwithhq.com/v1/apps/<saas-app-id>/auth/context
```

Require the returned SaaS app ID to match the one your integration expects. Keep the returned correlation ID with deployment or test evidence.

## 3. Discover objects, then search

```
curl --fail-with-body   -H "Authorization: Bearer $BWHQ_API_CREDENTIAL"   https://api.buildwithhq.com/v1/apps/<saas-app-id>/objects

curl --fail-with-body   -X POST   -H "Authorization: Bearer $BWHQ_API_CREDENTIAL"   -H "Content-Type: application/json"   -d '{"page":1,"pageSize":25,"sort":"created_desc"}'   https://api.buildwithhq.com/v1/apps/<saas-app-id>/objects/work-orders/records/search
```

## 4. Use a CLI profile for repeat work

```
bwhq auth profile add --name development   --saas-app-id <saas-app-id>   --credential-env BWHQ_API_CREDENTIAL   --set-current
bwhq doctor --json
bwhq auth login --json
```

A profile stores only metadata and a reference to the external credential source. It never stores or prints the bearer value.

Tip

Start with a read-only client. Add write, webhook, connector, AI, or installed-service scopes only when the integration has a tested reason to use them.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/quickstart.html).

---
title: "REST APIs"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/rest-apis.html"
reviewed_at: "2026-09-14"
authority: Official
---

# REST APIs

The current resource-oriented v1 API for app identity, records, connectors, webhooks, AI, logs, contracts, and installed services.

## In brief

- **Format:** JSON over HTTPS
- **Reference host:** api.buildwithhq.com
- **Data path:** API to reviewed services

The REST surface is the general-purpose integration layer for software outside BuildWithHQ. It is intentionally **resource-oriented**: callers work with applications, objects, records, relationships, workflows, and actions — not SQL tables, database names, or stored-procedure names.

## Current v1 resource families

- **Application metadata and schemas** — discover the objects/modules and fields an integration is allowed to use.
- **Permission-aware records** — list, search, retrieve, create, update, and archive records through reviewed server operations.
- **Relationships** — inspect record relationships using the application's declared model.
- **Connectors and inbound endpoints** — manage declared external integration metadata without returning provider secrets.
- **Webhooks** — manage event subscriptions, rotate signing secrets, inspect delivery evidence, and retry eligible failures.
- **AI and logs** — manage permitted AI ingestion/search/rebuild work and query bounded diagnostics.
- **Installed services** — invoke approved container-backed endpoints through the gateway rather than private addresses.

## Representative current routes

```
GET    /v1/apps/{saasAppId}/auth/context
GET    /v1/apps/{saasAppId}/objects
GET    /v1/apps/{saasAppId}/objects/{objectKey}/schema
POST   /v1/apps/{saasAppId}/objects/{objectKey}/records/search
POST   /v1/apps/{saasAppId}/objects/{objectKey}/records
PATCH  /v1/apps/{saasAppId}/objects/{objectKey}/records/{recordId}
DELETE /v1/apps/{saasAppId}/objects/{objectKey}/records/{recordId}
GET    /v1/apps/{saasAppId}/connector-types
GET    /v1/apps/{saasAppId}/logs/correlations/{correlationId}
```

Note

Use the generated OpenAPI document for the complete path set and schemas. These examples are current but intentionally do not duplicate the entire machine-readable reference.

## Server-derived scope

Do not design an integration around caller-supplied tenant, user, role, or location IDs. The gateway derives the credential's application and actor context, then applies the application's permission model server-side. IDs supplied as ordinary input never grant additional access.

## Reads and writes follow the same rule

Reads are filtered to the caller's allowed record envelope. Writes are stricter: a request must pass object-level, field/action-level, record-level, and application-level checks before the operation can execute. A valid JSON body is not proof that the caller is authorized to perform the change.

## Async operations

Long-running work — imports, large exports, AI jobs, appliance work, or other queued operations — should return `202 Accepted` with an operation identifier and a status resource instead of holding an HTTP request open indefinitely.

Tip

Build integrations against stable resource keys and returned schema metadata, not assumptions about BuildWithHQ's internal storage. That keeps your integration portable as the platform evolves.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/rest-apis.html).

---
title: "Authentication and API clients"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/authentication.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Authentication and API clients

Use isolated draft credentials for unpublished page JSON and an explicit live credential for publication and production operations.

## In brief

- **Draft:** bwk_draft · unpublished only
- **Live:** bwk_live · explicit publish
- **Secret rule:** Shown once; stored hashed

BuildWithHQ separates **who is calling** from **what that caller is allowed to do**. Human users use normal app or Builder Console sessions. Server-to-server integrations use one-time-displayed credentials created for one SaaS app.

## Four client classes, three bearer schemes

| Client class | OpenAPI scheme | Purpose |
| --- | --- | --- |
| Public | None | Health and explicitly public metadata only. |
| Draft app | `DraftAppCredential` / `bwk_draft_` | Read, edit, and validate unpublished page JSON. |
| Live app | `LiveAppCredential` / `bwk_live_` | Trusted-server production operations and explicit publication. |
| Delegated user | `DelegatedUserCredential` / `bwu_live_` | Short-lived calls executed as one verified tenant user. |

The generated OpenAPI JSON and YAML attach these schemes per operation. Code generators can therefore distinguish draft authoring, app-level production access, and user-delegated access instead of treating every bearer token as interchangeable.

## Draft and live are different credential classes

Use a `bwk_draft_` credential while a developer, CLI, or coding agent creates pages and edits unpublished page JSON. Draft credentials can hold `pages.draft.read` and `pages.draft.write`, plus `design.read`, `debug.read` and `debug.write`; they cannot read live tenant data, publish, or change the live app. When the draft has been reviewed, deliberately switch the trusted server to a `bwk_live_` credential with `pages.publish`. Publication names the exact draft-history ID and expected page version, so it cannot silently publish a newer or different draft. A live credential never reads or edits drafts.

```
# Draft key: save unpublished JSON
PUT /v1/apps/{saasAppId}/design/pages/Home/draft

# Draft key: validate and capture pageHistoryId + pageVersion
POST /v1/apps/{saasAppId}/design/pages/Home/validate

# Live key: the explicit release boundary
POST /v1/apps/{saasAppId}/design/pages/Home/publish
```

## Builder keys design as the app owner

Design routes run on your app's own design code, the same code as the in-app Design studio. Inside your app, a builder key acts as the app's owner (the single active owner of your app's first organization), and every saved draft and publish records both that owner and the key. Only the builder's own keys can design: delegated user tokens and keys tied to one tenant user are refused. Changes that affect the live app at once, such as custom fields, user types, menus and tenant policies, need a live key with `design.write`.

Debug sessions started with a builder key are the owner's debug sessions: the CLI, your own tools and the owner's in-app `+ Debug` drawer see the same sessions and history.

Tip

Let developers iterate on unpublished JSON with a draft key, from the CLI or your own tools. This reuses the canonical page history and validation system; there is no second development database to reconcile.

## Development uses the production contracts

This is not a stub or mock mode. An unpublished page can bind forms, checkboxes, lists, uploads, and action buttons to the same reviewed API operations and stored procedures used after publication. The server still enforces application, user, DataRole, location, revision, and action scope on every call. Switching to the live key grants release authority; it does not replace the backend or change the component contract.

## API clients

An API client is a non-human application identity. Each client has a name, an application boundary, an active/revoked state, and an explicit set of allowed scopes. The raw secret is generated securely and shown only when the client is created or rotated; the platform stores a non-reversible verification form rather than keeping the raw secret for later display.

- Create a separate client for each integration or environment.
- Give it only the scopes it needs.
- Rotate credentials without editing the integration's logical identity.
- Revoke a compromised or retired client immediately.
- Never place server credentials in public browser JavaScript.

## How a key is checked

The gateway looks a key up on the BuildWithHQ platform at most once a day. On every request it asks only your app's own database: whether the app is active, and whether the key has changed since that daily lookup. So:

- **Revoke** stops the key on its next request.
- **Rotate** stops the old secret on its next request; the new secret works at once.
- **Binding a key to a tenant user** takes effect on its next request.
- **Suspending the app** stops every key for that app on its next request.
- A **new key** can take up to a minute to start working if it was tried before it existed.

If the Builder Console reports that the app has not been told about a key change, the platform change is saved but the old key may keep working for up to a day. Retry the action, or rotate the key again.

## Current public scopes

| Area | Scopes |
| --- | --- |
| Records | `records.read` · `records.write` |
| Workflows | `workflows.read` · `workflows.execute` |
| Webhooks | `webhooks.read` · `webhooks.write` |
| Connectors | `connectors.read` · `connectors.write` · `inbound.write` |
| AI and logs | `ai.read` · `ai.write` · `logs.read` |
| Contracts, MCP, services | `contracts.read` · `mcp.use` · `appliances.read` · `appliances.invoke` |
| Page development | `pages.draft.read` · `pages.draft.write` · `pages.publish` |
| App design and debug | `design.read` · `design.write` (live key) · `debug.read` · `debug.write` |

First-class module routes add 48 registered least-privilege scopes in the form `modules.<module-key>.read` and `modules.<module-key>.write`. Use the exact `requiredScopes` value in `catalog/operations.json` or the API route explorer instead of constructing a scope from a page label.

## Scopes are only the first gate

A scope such as `records.read` means the client may ask to read records; it does *not* mean every record becomes visible. The API still applies the application's server-side record, DataRole, location, and capability rules appropriate to that identity.

## Human sessions

When a human-facing application calls the API on behalf of a signed-in user, the gateway uses that verified user context. UI decisions can hide unavailable actions for convenience, but the server repeats authorization on every request.

Signing in to your app is the only time the app asks the BuildWithHQ platform about itself. Each sign-in records that check in the app's own database; after that, requests and token renewals use the app's own database only.

## OAuth connections are provider credentials, not API identity

The OAuth connection endpoints let an app connect to a registered external provider using authorization code + PKCE. They do not replace the BuildWithHQ API credential that authenticates the caller to the gateway.

Important

Never accept CustomerAccountId, AppAccountId, user role, or permission claims from a normal request body as proof of identity. Those values must come from verified server-side context.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/authentication.html).

---
title: "Requests, responses, errors, and correlation IDs"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/request-conventions.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Requests, responses, errors, and correlation IDs

The conventions every client should apply for JSON, pagination, safe errors, retries, and operational evidence.

## In brief

- **Format:** JSON over HTTPS
- **Page size:** 1–100 for record search
- **Evidence:** Correlation ID

Use the generated OpenAPI operation and schema as the exact contract. The rules below are the cross-cutting behavior a production client should implement once and reuse for every operation.

## Headers and content

- Send the credential as `Authorization: Bearer <credential>`.
- Send JSON request bodies as `application/json`.
- Retain the server-issued `X-Correlation-ID` from each response. A caller-supplied value is an untrusted hint and is not echoed as the server's audit identity; use supported W3C trace context for cross-service tracing.
- Never log authorization headers, secret references, OAuth codes, webhook secrets, or full sensitive payloads.

## Pagination and bounds

Record search uses one-based `page` and a bounded `pageSize` from 1 through 100. Query text is bounded to 400 characters. Other list endpoints expose their own limits in OpenAPI; do not assume one pagination shape fits every resource.

## Safe error handling

| Status | Client behavior |
| --- | --- |
| `400` | Fix validation or request shape; do not retry unchanged input. |
| `401` | Resolve or rotate the credential; never fall back to a broader credential automatically. |
| `403` / safe `404` | Do not probe for cross-app existence. Verify app binding and required scope. |
| `409` | Reload current state and resolve the concurrency or lifecycle conflict. |
| `422` | Show the domain, plan, or policy failure to an operator. |
| `429` | Honor `Retry-After` and back off with jitter. |
| `5xx` | Retry only safe/idempotent work, with a bounded backoff and the same logical request key where supported. |

## Do not parse internal diagnostics

Error responses provide a stable contract version, safe code/message, and correlation ID. Database names, stored procedures, server paths, provider secrets, and stack traces are deliberately absent. Treat wording as human-readable context and branch on documented codes/status instead.

Tip

A useful integration log entry contains the operation ID, app ID, HTTP status, duration, and correlation ID—never the bearer credential or a raw secret.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/request-conventions.html).

---
title: "Permission-aware data access"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/data-access.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Permission-aware data access

Every data surface resolves through the same record, role, location, and capability envelope.

## In brief

- **Isolation:** Application-scoped
- **Filtering:** Server-side
- **Query exposure:** No SQL or procedure names

BuildWithHQ's data model is designed around a simple promise: **an integration should never see more data merely because it used an API instead of the application UI.**

## The permission envelope

Before data is returned or an action is executed, the runtime can combine several dimensions of context:

- the authenticated application/account;
- the user or API-client identity;
- DataRole membership and capability permissions;
- record-to-role sharing;
- location scope;
- the object/module and requested action; and
- additional policy attached to the specific field, workflow, or extension endpoint.

This evaluation happens on the server. A caller cannot broaden access by modifying a hidden field, adding another record ID, or requesting a different transport.

## Data keys

For dashboards, composed pages, AI context, and other curated reads, BuildWithHQ can expose **named data keys**: registered operations with known parameters and known result shapes. A caller asks for the key, not a query string or procedure name.

```
{
  "dataKey": "inbox.kpis",
  "parameters": {}
}
```

Data keys are useful when a page needs a secure, purpose-built JSON shape rather than generic record CRUD. REST resources and data keys complement each other: resource APIs cover general integration needs; data keys cover reviewed, high-level projections.

## AI and MCP follow the same envelope

AI features do not receive a privileged copy of the database. MCP tools and AI context retrieval should resolve through the same secured record set, with AI-specific permissions applied where configured.

Tip

Design one authorization kernel and reuse it everywhere. REST, workflows, MCP, and container calls should differ in transport — not in what they are allowed to see.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/data-access.html).

---
title: "Connectors, OAuth, and provider secrets"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/connectors-and-oauth.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Connectors, OAuth, and provider secrets

Discover supported connector types and configure data, payment, and OAuth connections without sending raw provider secrets.

## In brief

- **Discovery:** Registered connector catalog
- **Secrets:** References only
- **OAuth:** Authorization code + PKCE

The connector registry tells a client which integration families and capabilities the current gateway supports. The public set includes REST and GraphQL data connectors, outbound webhooks, standard OAuth connections, Stripe payment connectors, and installed services.

## Discover before configuring

```
GET /v1/apps/{saasAppId}/connector-types
GET /v1/apps/{saasAppId}/data-connectors
GET /v1/apps/{saasAppId}/payment-connectors
GET /v1/apps/{saasAppId}/oauth-connections
```

Discovery is permission-filtered and returns public connector metadata—not connector instances belonging to another app, secret references, destination secrets, tenant routing, or internal database connector types.

## Data connectors

REST and GraphQL connectors require public HTTPS endpoints. Mutating operations must be explicitly allowlisted. Create and update requests accept a protected secret reference, never the raw provider credential itself.

## Payment connectors

The current payment connector type is Stripe. Provider endpoints remain server-owned, and both credential and webhook-secret references are required where applicable. Arbitrary provider types and caller-selected provider base URLs are rejected.

## OAuth lifecycle

1. Start an authorization for a registered provider and requested provider scopes.
2. Redirect the user to the returned provider authorization URL.
3. Complete the one-time state with the provider code.
4. Refresh or revoke by the returned connection ID.

The platform uses authorization code + PKCE, one-time hashed state, encrypted token envelopes, and leased refresh/revoke operations. Provider authorization/token endpoints and client credentials are registered server-side.

Important

A secret reference identifies protected server-side material. Do not send the underlying credential in a connector JSON document or store it in frontend state.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/connectors-and-oauth.html).

---
title: "Inbound endpoints"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/inbound-endpoints.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Inbound endpoints

Create app-bound inbound entry points, rotate keys, and process incoming events through authenticated application APIs.

## In brief

- **Scope:** inbound.write
- **Identity:** Server-derived app
- **Rotation:** Explicit endpoint operation

Inbound endpoints give an external system a controlled entry point into one SaaS app. The platform authenticates, validates, and routes each accepted event through its application service contracts.

## Current operations

```
GET  /v1/apps/{saasAppId}/inbound-endpoints
POST /v1/apps/{saasAppId}/inbound-endpoints
POST /v1/apps/{saasAppId}/inbound-endpoints/{endpointId}/rotate
```

The authenticated credential establishes the app boundary. A path ID selects an endpoint inside that boundary; it does not grant access to an endpoint owned by another app.

## Key handling

Treat an endpoint key like any other integration secret: capture it only from the authorized create/rotate response, store it in a secret manager, and rotate it immediately after suspected disclosure. Never place it in source control, URLs, screenshots, or browser bundles.

## Processing model

Validate and acknowledge inbound requests quickly, then perform durable work asynchronously. Use stable external event IDs where the source provides them so retries do not create duplicate business activity.

Tip

Document the source system, owning team, rotation owner, and last tested date for every inbound endpoint. An unlabeled endpoint becomes an incident during the first key rotation.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/inbound-endpoints.html).

---
title: "Webhooks and event delivery"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/webhooks.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Webhooks and event delivery

Push signed application events to external systems with retries, idempotency, and observable delivery history.

## In brief

- **Scopes:** account | app
- **Default:** account
- **Transport:** Signed HTTPS POST

Webhooks are the outbound event surface of the developer platform. Instead of repeatedly polling the REST API, an integration registers an HTTPS destination and receives events when relevant application activity occurs.

## Choose a reachable destination

Set `destinationUrl` to a public HTTPS endpoint, at most 2048 characters, without a username, password, or fragment. Create and update requests reject private, loopback, link-local, multicast and reserved IP addresses, including IPv4 addresses written as IPv6. For example, `0.1.2.3`, `100.64.0.1`, `198.18.0.1` and `fd00::1` are not valid destinations. Use your public receiver URL instead.

An invalid destination returns HTTP 400 with correction guidance and a correlation ID. Hostname acceptance does not prove reachability: before each delivery the worker checks every resolved address and refuses the destination if any address is disallowed. Redirects are not followed. Correct an existing invalid subscription before retrying its deliveries.

[Open the Webhook Lab](https://webhooks.buildwithhq.com/) [Receiver and polling walkthrough](webhook-receiver-and-background-jobs.html) [Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip)

## Choose the subscription scope

Set `scope` to `account` for records and activity belonging only to the credential's organization. Set it to `app` when the SaaS builder's trusted backend must synchronize customer organizations and users across the whole SaaS app. Existing subscriptions default to `account`; changing scope is explicit.

| Scope | Receives | Use it for |
| --- | --- | --- |
| `account` | Matching events for the credential's own customer organization. | Ordinary record and account-local integrations. This is the backward-compatible default. |
| `app` | The nine organization, user, membership, and invitation lifecycle events for every customer organization in the SaaS app. | A SaaS builder's controlled billing, CRM, identity, or onboarding backend. |

An app-scoped delivery still includes the customer `organizationId`. It does not give the receiver database access or permission to call APIs as that organization. App scope accepts only the nine lifecycle keys below; it cannot be paired with record events to bypass ordinary record scopes.

```
// Account-local record subscription (scope may be omitted)
{
  "displayName": "Account record sync",
  "destinationUrl": "https://hooks.example.com/records",
  "scope": "account",
  "events": [{ "eventKey": "record.updated", "eventVersion": "2026-08-01" }]
}

// App-wide customer lifecycle subscription
{
  "displayName": "Customer lifecycle sync",
  "destinationUrl": "https://hooks.example.com/lifecycle",
  "scope": "app",
  "events": [{ "eventKey": "organization.created", "eventVersion": "2026-09-14" }]
}
```

## Organization and user lifecycle events

| Event | Emitted when |
| --- | --- |
| `organization.created` | A customer organization is provisioned. |
| `organization.updated` | Name, billing email, status, or other published organization state changes, including reactivation. |
| `organization.deactivated` | The organization transitions to inactive. |
| `user.created` | A tenant user identity is created inside an organization. |
| `user.updated` | Published profile, type, owner, or active state changes, including reactivation. |
| `user.deactivated` | The user transitions to inactive. |
| `membership.created` | The user becomes a member of the organization. |
| `membership.role_changed` | User type, owner status, or DataRole assignments change. |
| `invitation.accepted` | A delivered invitation is consumed and linked to its accepted user. |

These events use version `2026-09-14` and are classified as sensitive because they can contain names or email addresses. Subscribe only a controlled backend and retain only the fields your billing, CRM, identity, or onboarding workflow needs.

## Event contract

Each delivery should have a stable event identifier, event type, schema version, occurrence time, application context, subject identifiers, and a data object. The event ID is the consumer's idempotency key.

```
{
  "id": "2a96f714-3653-4db4-bb63-7464bb5e4339",
  "type": "membership.role_changed",
  "version": "2026-09-14",
  "occurredAt": "2026-09-14T23:15:00Z",
  "appId": "7aa2...",
  "subject": {
    "type": "membership",
    "id": "e913..."
  },
  "actor": { "kind": "system" },
  "data": {
    "organizationId": "871c...",
    "userId": "e913...",
    "userTypeKey": "manager",
    "dataRoles": [{ "dataRoleId": 14 }]
  }
}
```

## Current management routes

```
GET  /v1/apps/{saasAppId}/webhook-event-types
GET  /v1/apps/{saasAppId}/webhooks
POST /v1/apps/{saasAppId}/webhooks
PUT  /v1/apps/{saasAppId}/webhooks/{subscriptionId}
POST /v1/apps/{saasAppId}/webhooks/{subscriptionId}/rotate-secret
GET  /v1/apps/{saasAppId}/webhook-deliveries
POST /v1/apps/{saasAppId}/webhook-deliveries/{deliveryId}/retry
```

## Receiving safely

1. Read the raw request body.
2. Verify the delivery signature and timestamp before trusting the JSON.
3. Reject payloads outside the replay window.
4. Use the event ID to make processing idempotent.
5. Return `2xx` quickly and do heavy work asynchronously.

Verify `X-BuildWithHQ-Timestamp` and `X-BuildWithHQ-Signature` over the exact bytes received. The signed value is `<timestamp>.<raw-body>`; the signature uses HMAC-SHA256 and is formatted as `v1=<lowercase-hex>`. Reject timestamps more than five minutes from your server clock. Delivery and event identifiers are also supplied in `X-BuildWithHQ-Delivery` and `X-BuildWithHQ-Event`.

## Delivery behavior

Lifecycle changes enter a transactional outbox with the database mutation, then the ordinary signed delivery worker promotes and delivers them. Multiple role writes inside one database transaction collapse to the final membership payload. Network failures still make delivery at-least-once rather than exactly-once: deduplicate by event ID and compare `occurredAt` or fetch current API state before applying an older event.

## Developer operations

The API exposes event discovery, subscription create/update, signing-secret rotation, bounded delivery evidence, and manual retry of eligible failed deliveries. Failed attempts retain safe status, duration, category, and bounded response evidence rather than unbounded remote bodies.

Note

Event keys and versions come from the event-type endpoint. Do not hard-code an event catalog copied from prose, and do not retry a delivery unless its current state is eligible for the explicit retry operation.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/webhooks.html).

---
title: "Webhook receiver and background-job polling examples"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/webhook-receiver-and-background-jobs.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Webhook receiver and background-job polling examples

Run the exact-body webhook receiver and bounded AI rebuild poller published at webhooks.buildwithhq.com.

## In brief

- **Examples:** Dependency-free Node.js
- **Receiver:** Verify, queue, then acknowledge
- **Poller:** Bounded + Retry-After

[`webhooks.buildwithhq.com`](https://webhooks.buildwithhq.com/)  publishes runnable examples for the two async integration patterns developers need first: accepting signed events in their own backend and polling a public background job to terminal state. The reference site does not collect or retain customer webhook payloads.

[Download receiver](https://webhooks.buildwithhq.com/examples/webhook-receiver.mjs) [Download poller](https://webhooks.buildwithhq.com/examples/background-job-poller.mjs) [Download offline tests](https://webhooks.buildwithhq.com/examples/examples.test.mjs)

## 1. Run the receiver locally

```
$env:BWHQ_WEBHOOK_SIGNING_SECRET = "the one-time subscription secret"
$env:BWHQ_WEBHOOK_QUEUE_DIR = "C:\ProgramData\MySaaS\webhook-queue"
node webhook-receiver.mjs
```

Publish the local `/webhooks/buildwithhq` route through your own HTTPS reverse proxy and register that URL as the subscription destination. Keep the signing secret and queue storage in the trusted backend.

## 2. Verify, deduplicate, queue, acknowledge

1. Read no more than the configured body limit as exact bytes.
2. Verify HMAC-SHA256 over `<timestamp>.<raw-body>` before parsing.
3. Reject timestamps outside five minutes and malformed envelopes.
4. Atomically accept the event UUID once in durable storage.
5. Return 202 for a new queued event or 200 for a known event.
6. Process later with an idempotent CRM, billing, identity, or onboarding handler keyed by `event.id`.

The example logs only event ID, type, and version. Replace its filesystem store with a production queue or database when needed, retaining a unique event-ID constraint. The downstream mutation must also be repeat-safe because a worker can fail after applying the effect and before recording completion.

## 3. Poll the public background-job contract

The corrected file example flushes staging files before atomic publication and validates duplicate bytes. Worker passes share a directory lock, and failed handlers move to a failed-event marker after three attempts so later events continue. Monitor `failed/`. After a crash, stop all workers before removing a stale `worker.lock`. To replay a failed event, fix its cause and remove only its failed and attempts markers while workers are stopped. Keep the accepted payload. Use a transactional broker or database when production power-loss durability is required; the local hard-link file store is a reference implementation.

Polling deadlines cover requests and waits. Cancellation interrupts both, and a Retry-After exceeding the remaining budget fails without issuing an early retry.

The current public pollable job is an AI rebuild. Queue it once through `POST /v1/apps/{saasAppId}/ai/rebuilds`, retain `jobId`, then read `GET /v1/apps/{saasAppId}/ai/rebuilds/{jobId}`. Queueing requires `ai.write`; status requires `ai.read`; the caller also needs current tenant account-owner authority.

```
const result = await pollAiRebuild({
  saasAppId: process.env.BWHQ_SAAS_APP_ID,
  credential: process.env.BWHQ_USER_TOKEN,
  jobId: receipt.jobId,
  maximumWaitMs: 10 * 60 * 1000,
});
```

The example stops on `completed`, `failed`, or `cancelled`, sleeps between other states, honors the required whole-second `Retry-After` header after 429, supports cancellation, and enforces a maximum wait. It never automatically repeats the queue POST after an uncertain response.

## 4. Verify without credentials

```
node --test examples.test.mjs
```

The offline tests send signed raw bytes to a loopback receiver, reject a bad signature, prove duplicate acknowledgement and one-time processing, then exercise queued, rate-limited, completed, and failed polling responses.

Note

An asynchronous installed-service invocation returns an invocation ID that is also its durable task ID. Poll GET /v1/apps/{saasAppId}/services/invocations/{invocationId} with appliances.read, or request revision-fenced cooperative cancellation through POST /v1/apps/{saasAppId}/services/invocations/{invocationId}:cancel with appliances.invoke. These are separate from the AI rebuild job contract.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/webhook-receiver-and-background-jobs.html).

---
title: "Logs, diagnostics, and correlation tracing"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/logs-and-observability.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Logs, diagnostics, and correlation tracing

Tail and search bounded app logs, then follow one correlation ID across related operational evidence.

## In brief

- **Scope:** logs.read
- **Boundary:** App-scoped
- **Primary key:** Correlation ID

The Developer API exposes operational evidence without opening tenant log tables or returning infrastructure routes. Every query is bound to the authenticated SaaS app and returns bounded, sanitized results.

## Current routes

```
GET /v1/apps/{saasAppId}/logs/tail
GET /v1/apps/{saasAppId}/logs/search
GET /v1/apps/{saasAppId}/logs/correlations/{logCorrelationId}
```

## A practical incident workflow

1. Capture the correlation ID from the failing API response, webhook delivery, CLI output, or user-visible error.
2. Query the correlation route first; it is more precise than a broad text search.
3. Use search for a known safe term, component, or error code when no correlation ID exists.
4. Use tail only for a short live observation window.
5. Record the correlation ID—not a copied secret or full customer payload—in the incident ticket.

## What is intentionally absent

The log API returns bounded operational evidence and omits connection strings, database/server names, provider credentials, raw authorization headers, operator-only stack traces, and unrestricted tenant data.

Tip

Make correlation ID a first-class field in your integration logger. It turns support from timestamp guessing into one bounded lookup.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/logs-and-observability.html).

---
title: "AI ingestion, rebuilds, and multimodal search"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/ai-api.html"
reviewed_at: "2026-09-14"
authority: Official
---

# AI ingestion, rebuilds, and multimodal search

Use the secured tenant AI surface for authorized record ingestion, rebuild operations, and Qwen3-VL search.

## In brief

- **Scopes:** ai.read · ai.write
- **Model:** Qwen3-VL-Embedding-8B
- **Vector lanes:** 256 · 1024 · 1998

The AI API is app-bound and permission-aware. It does not give an API client a privileged copy of tenant records: runtime identity, DataRole, location, permission keys, and `CanAiReadRecords` are resolved before context is assembled.

## Current routes

```
GET  /v1/apps/{saasAppId}/ai/status
POST /v1/apps/{saasAppId}/ai/sources/records/{recordId}/ingest
POST /v1/apps/{saasAppId}/ai/rebuilds
GET  /v1/apps/{saasAppId}/ai/rebuilds/{jobId}
POST /v1/apps/{saasAppId}/ai/search
```

## Ingestion and rebuilds are operations

Queue work, retain the returned job/correlation evidence, and poll the documented status resource. Do not repeatedly enqueue a new rebuild because one request timed out. Search is read-only; ingestion and rebuilds require `ai.write`.

## Multimodal evidence

The target embedding model is `Qwen/Qwen3-VL-Embedding-8B`. Documents preserve visual evidence for tables, charts, diagrams, and screenshots, with supported 256, 1024, and 1998-dimensional lanes. Clients choose documented search modes rather than uploading arbitrary vectors or assuming legacy dimensions.

**Permission behavior:** AI retrieval uses the normal secured record path. Records outside the resolved identity's access never enter prompt, retrieval, reranking, citation, or response context.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/ai-api.html).

---
title: "Workflows and custom actions"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/workflows.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Workflows and custom actions

Build durable server-side automations from native actions, approvals, waits, webhooks, AI actions, and extension services.

## In brief

- **Execution:** Server-side
- **Published runs:** Snapshot configuration
- **Extensibility:** Native + webhook + container actions

Workflows are BuildWithHQ's server-side orchestration layer. They let a builder connect application events to durable sequences of actions without pushing business logic into a browser.

## Workflow lifecycle

1. **Draft** a definition and add ordered steps.
2. **Validate and publish** the definition.
3. **Trigger a run** manually, from record activity, on a schedule, or from another approved source.
4. **Snapshot the steps** into the run so later edits cannot change an in-flight execution.
5. **Workers claim work** with leases, execute one step at a time, and record outcomes.
6. **Wait, pause for approval, continue, fail, or cancel** without losing the run history.

## Built-in step families

The workflow model supports step families such as notifications, record updates, assignments, tags, follow-ups, messages, billing actions, waits, human approvals, AI actions, and outbound webhook calls. Custom container-backed actions can extend that list without moving the workflow engine into the customer container.

## Failure policy belongs to the step

A step can define what the run should do when execution fails: stop the run, skip the failed step, or continue according to the workflow's policy. That makes failure behavior part of the automation definition rather than an undocumented worker decision.

## Custom actions

A reusable custom action should declare a stable key, display name, input schema, output schema, required permissions/connections, execution target, and optional outcome branches. The builder UI can then render the configuration form from that contract while the runtime validates it again at execution.

```
{
  "key": "company.enrich",
  "inputSchema": {},
  "outputSchema": {},
  "requiredPermission": "records.write",
  "execution": {
    "type": "containerEndpoint",
    "endpointKey": "company.enrich"
  }
}
```

Note

The current generated public v1 OpenAPI contract does not expose workflow-definition or workflow-run endpoints. Use the Builder/tenant workflow surfaces today; do not invent REST paths from this conceptual lifecycle.

Tip

Treat a published workflow as executable application logic. Version it, test it, and keep its inputs/outputs as explicit as an API endpoint.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/workflows.html).

---
title: "MCP tools for AI clients"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/mcp-tools.html"
reviewed_at: "2026-09-14"
authority: Official
---

# MCP tools for AI clients

Expose approved API-backed application capabilities to MCP-compatible AI clients under the same permission envelope.

## In brief

- **Transport:** Stateless Streamable HTTP
- **Catalog:** 43 permission-filtered tools
- **Scopes:** mcp.use + tool scope

Model Context Protocol (MCP) gives AI clients a standard way to discover and call tools. BuildWithHQ's opportunity is to generate those tools from the application capabilities that already exist instead of maintaining a separate AI-only integration layer.

## What becomes a tool

An application's MCP catalog can be assembled from approved capabilities such as:

- permission-aware record search and retrieval;
- safe record actions and registered data operations;
- published workflows that are allowed to be started by the caller;
- approved container/appliance endpoints with declared schemas; and
- AI-specific actions that are explicitly enabled for the user's role.

## Generated, not privileged

MCP is a protocol adapter over the same application service layer used by REST. Tool discovery itself is filtered: if an identity cannot invoke a capability, that capability is not offered.

## Current endpoint

### Protocol compatibility and evidence

The current Release implementation uses the reviewed official ModelContextProtocol.AspNetCore 2.2.0 package in explicit stateless mode. On September 22, 2026, public release `1.20.14-task34l-mcp-conformance-20260922-v1` passed authenticated HTTPS probes for `2026-07-28` discovery and listing without initialization/session IDs, required-header mismatch rejection, legacy `2025-06-18` initialization, wrong-app and missing-scope catalog isolation, continuation rejection, and credential revocation. Public release `1.20.15-task34n-governed-skills-20260922-v2` added governed Skills. Release `1.20.16-task34m-mcp-tasks-20260922-v2` advertises the reviewed Tasks extension and passed a 12-check public journey covering capability discovery, REST and MCP reads, effective and requested cancellation, stale-revision rejection, worker-boundary cancellation, read-only denial, cross-task/cross-app rejection, cleanup, and exact release identity. These are bounded interoperability results rather than a claim that every client or optional extension is certified.

**Advertised extensions:** governed Skills and durable installed-service Tasks. Skills are available through negotiated `skills/list`, `skills/get`, and digest-bound `resources/read`. Tasks are available through negotiated `tasks/get`, `tasks/update`, and `tasks/cancel`; every call reauthorizes, and installed-service `tasks/update` cannot invent an unsupported `input_required` state. These are protocol methods, not entries in the curated MCP tool-name map. BuildWithHQ tools do not currently accept MRTR continuations: payloads containing `requestState` or `inputResponses` fail closed and cannot approve or replay a mutation. Permission-filtered catalogs return `cacheScope: private`, `ttlMs: 0`, and `Cache-Control: private, no-store`; clients must not reuse a catalog across an app, organization, user, scope set, or approval revision.

**Authentication boundary:** the MCP endpoint accepts the Developer API's app-scoped bearer credential or a short-lived delegated-user credential. BuildWithHQ does not currently claim MCP authorization-server metadata, dynamic client registration, CIMD, or OAuth interoperability certification. The `oauth_connections.*` tools configure external provider connections; they are not MCP client authorization.

See the official [2026-07-28 release](https://blog.modelcontextprotocol.io/posts/2026-07-28/), [Tasks extension](https://tasks.extensions.modelcontextprotocol.io/specification/draft/tasks)  and [Skills extension specification (Beta)](https://skills.extensions.modelcontextprotocol.io/specification/beta/skills). Extension support must be discovered, never inferred from the base protocol version.

### Four identity surfaces, not four interchangeable credentials

| Surface | Authority and current status |
| --- | --- |
| Builder Account MCP | Planned builder-management adapter. Builder-owned apps, templates and releases need builder authorization; an app key cannot substitute for it. |
| Developer VM MCP | Planned workspace adapter. Repository, build and sandbox permissions remain separate from production tenant permissions; deployment requires explicit policy. |
| SaaS Application MCP | Available app-bound endpoint with server-held app credentials, tool scopes and per-app sensitive-tool approval. |
| End-Customer MCP | The same app endpoint accepts short-lived delegated TenantUser credentials; DataRole, location and record authorization remain server-derived. No independent end-customer endpoint is claimed. |

### Durable Tasks and governed Skills

Durable Tasks currently project installed-service invocation state through REST and MCP without creating a second execution queue. The invocation ID is the task ID. Status requires `appliances.read`; cancellation requires `appliances.invoke` and can report `requested`, `effective`, or `too_late`. An optional revision fence rejects stale cancellation, and committed native effects are never described as undone. Workflow and AI-job projections remain future mappings. Governed Skills serve exact-version, digest-verified resources at builder, SaaS application, tenant organization, user, and GoClaw scopes. A delegated active tenant owner can assign an existing immutable Skill version to that organization’s GoClaw through the REST API. Skill instructions and dependency declarations never grant permissions, tools, records, or approval authority.

The stateless Streamable HTTP endpoint is `/v1/apps/{saasAppId}/mcp`. The API credential must carry `mcp.use` plus the ordinary scope required by each discovered tool, such as `records.read`, `webhooks.write`, or `appliances.invoke`.

The generated OpenAPI contract publishes the transport as POST operation `developerMcpInvoke` with an opaque JSON-RPC request/response envelope. `catalog/operations.json` publishes `requiredScopes: ["mcp.use"]`; the generated 43-tool name map supplies each tool's additional operation scope.

[Connect DeepSeek Harness](deepseek-harness.html) [Download the tested patch](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip)

## Tool contracts

`mcp/deepseek-harness-tool-names.json` schema version 2 publishes every tool's stable name, DSH-visible name, required arguments, scopes, side-effect class, and tested client version. Sensitive mutations additionally publish an `approval` object containing the exact capability key, required Builder permission, and management surface. The two concurrency-fenced module writes include complete JSON input schemas.

| Tool | Required arguments | Per-app approval |
| --- | --- | --- |
| `buildwithhq.checklists.toggle_item` | `checklistRunItemId`, `expectedRevision`, `nextChecked` | `checklists.toggle_item`; approver needs `CanManageApiKeys` |
| `buildwithhq.work_orders.update_status` | `recordId`, `expectedUpdatedUtc`, `status` | `work_orders.update_status`; approver needs `CanManageApiKeys` |

Each tool has a stable name, description, JSON input schema, output schema, required permission, side-effect classification, and — for sensitive mutations — an app-specific approval policy. Read tools and write tools are visibly distinguishable to both AI clients and users.

## Approve sensitive tools for one app

1. Open the Builder Console and select the SaaS app.
2. Open **Manage API clients**.
3. Under **MCP sensitive tools**, review the tool name, effect, and required API scope.
4. Select **Approve**. Revoke it from the same screen when the agent no longer needs it.

Approval applies only to the selected SaaS app. A credential must still carry `mcp.use` and the tool's exact required scope. Approved tools become discoverable on the next stateless MCP request; revoked tools disappear on the next request. Every approve and revoke action writes a correlated builder audit row.

## Auditability

Every mutation performed through MCP should carry correlation and actor context into the normal application audit path. For container-backed tools, the platform can also record the resolved endpoint identity and invocation outcome so an administrator can explain what code actually ran.

## First-class module tools

Nine curated reads expose Universal Inbox, Work Orders, Checklists & Signoffs, Global Search, and AI Insights directly. Two sensitive writes, `buildwithhq.checklists.toggle_item` and `buildwithhq.work_orders.update_status`, call the same secured application services and stored procedures as their REST routes. They require the exact module write scope, preserve optimistic-concurrency tokens, and remain hidden until a permitted builder approves them for that SaaS app.

Note

The current catalog contains 43 tools mapped to shared capability adapters. buildwithhq.services.list dynamically returns installed endpoint schemas under appliances.read; invocation remains separately protected. Read, mutating, and sensitive side effects are classified; sensitive capabilities are default-deny until a permitted builder approves each capability for that SaaS app.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/mcp-tools.html).

---
title: "Use BuildWithHQ with DeepSeek Harness"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/deepseek-harness.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Use BuildWithHQ with DeepSeek Harness

Connect DeepSeek Harness to the curated BuildWithHQ MCP surface with a tested Streamable HTTP patch, app or delegated-user identity, and exact tool-name mapping.

## In brief

- **Tested client:** dsh-mcp-client 0.1.2-rc.1
- **Transport:** Streamable HTTP
- **Tool ceiling:** 43 curated tools

DeepSeek Harness can use BuildWithHQ as a governed application backend through MCP. The same endpoint works for BuildWithHQ builders and API43 headless applications: DSH discovers only the tools allowed by the credential, and every call still passes through app binding, scopes, DataRoles, Locations, record permissions, rate limits, and audit.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Understand the MCP security model](mcp-tools.html) [Build a headless SaaS](headless-saas.html)

## 1. Install the tested DSH release

DeepSeek Harness is moving quickly, so this guide pins the versions exercised by BuildWithHQ. Install DSH, then add the MCP client to the profile you plan to run.

| Dependency | Tested version |
| --- | --- |
| BuildWithHQ / API43 Developer Kit | 1.20.70 |
| DeepSeek Harness CLI | 0.1.2-rc.1 |
| `@deepseek-ai/dsh-mcp-client` | 0.1.2-rc.1 |
| `@deepseek-ai/cordis` | 4.0.2 |
| pnpm | 10.15.1 |
| BuildWithHQ MCP server SDK | ModelContextProtocol.AspNetCore 2.2.0 |

Re-run initialization, discovery, delegated call, revocation, reconnection, schema, and name-map tests before changing a tested version.

### Windows PowerShell

```
npm install --global pnpm@10.15.1 @deepseek-ai/dsh@0.1.2-rc.1
dsh plugin --profile web add @deepseek-ai/dsh-mcp-client@0.1.2-rc.1
```

### Linux or macOS

```
npm install --global pnpm@10.15.1 @deepseek-ai/dsh@0.1.2-rc.1
dsh plugin --profile web add @deepseek-ai/dsh-mcp-client@0.1.2-rc.1
```

## 2. Copy the Cordis patch

Developer Kit 1.20.70 contains this file at `mcp/deepseek-harness.cordis.patch.yml`. It contains environment references, not credentials, so the same checked-in patch can be used in development and deployment.

```
- insert:
    - id: mcp-buildwithhq
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: buildwithhq
        transport: streamable-http
        url: !!js '`https://api.buildwithhq.com/v1/apps/${process.env.BWHQ_SAAS_APP_ID}/mcp`'
        headers:
          Authorization: !!js '`Bearer ${process.env.BWHQ_API_CREDENTIAL}`'
        toolCallTimeoutMs: 60000
        failOnStartupError: true
        reconnect:
          enabled: true
          initialDelayMs: 500
          maxDelayMs: 30000
          maxAttempts: 10
```

## 3. Supply the app and credential

```
$env:BWHQ_SAAS_APP_ID = "<your-saas-app-id>"
$env:BWHQ_API_CREDENTIAL = "<server-held-bwk-or-short-lived-bwu>"
dsh --profile web --patch .\mcp\deepseek-harness.cordis.patch.yml --no-open
```

Linux or macOS:

```
export BWHQ_SAAS_APP_ID="<your-saas-app-id>"
export BWHQ_API_CREDENTIAL="<server-held-bwk-or-short-lived-bwu>"
dsh --profile web --patch ./mcp/deepseek-harness.cordis.patch.yml --no-open
```

The endpoint assembled by the patch is `https://api.buildwithhq.com/v1/apps/{saasAppId}/mcp`. An app-bound `bwk_live_` credential is appropriate only in a trusted server environment. Never place it in browser JavaScript, a page document, a prompt, source control, or a downloadable configuration.

## 4. Act as the signed-in end user

For a headless browser or user-specific agent, your trusted backend authenticates the person first and exchanges its app credential for a 2-15 minute `bwu_live_` delegated token. Request `mcp.use` plus only the operation scopes that session needs. DSH then calls MCP as that TenantUser; it does not receive an app-wide master key.

```
{
  "providerKey": "your-auth-provider",
  "externalAccountId": "organization-42",
  "externalSubject": "user-1837",
  "scopes": ["mcp.use", "records.read"],
  "lifetimeMinutes": 10
}
```

Revocation, expiry, user deactivation, role changes, and location changes are enforced by the server. Because the patch creates a fixed Authorization header when the profile starts, restart the DSH profile after replacing an expired or revoked token.

## 5. Understand the tool names

BuildWithHQ keeps readable dotted raw names, such as `buildwithhq.records.objects.list`. DSH permits only letters, digits, underscores, and hyphens and limits public tool names to 64 characters. The tested client therefore exposes that example as:

```
mcp__buildwithhq__buildwithhq_records_objects_list_46db665ef811
```

Do not reproduce the normalization algorithm in application code. Use `mcp/deepseek-harness-tool-names.json` from the kit; it records the exact raw name, DSH-visible name, required arguments, required scopes, side-effect class, approval capability, and tested DSH client version for all 43 tools.

## First-class module tools

The catalog includes direct secured reads for Universal Inbox, Work Orders, Checklists & Signoffs, Global Search, and AI Insights. It also includes approval-gated checklist toggles and Work Order status changes. Grant the corresponding module scope; the write tools additionally require per-app builder approval. Every module tool executes the same application service and stored procedure as its matching REST route.

For example, use `buildwithhq.work_orders.search` to find authorized Work Orders and `buildwithhq.inbox.list` to list the delegated user’s Universal Inbox. Read the generated name map for the corresponding DSH-visible names instead of deriving them.

## Why 43 tools instead of all 422 REST operations?

Every registered tool schema consumes model context on every request. Publishing hundreds of nearly adjacent CRUD operations makes tool choice worse and spends tokens before the user asks a question. BuildWithHQ keeps the complete REST surface in OpenAPI and the typed SDK, while MCP presents 43 stable intent-level tools for key modules, records, connectors, inbound endpoints, webhooks, and appliances.

Forty-three is the registered ceiling, not a promise that every identity sees 43. Discovery is permission-filtered. A Work Orders reader sees its module tools but not Inbox or connector writes; sensitive mutations are hidden until a permitted builder approves them for that SaaS app.

## Connection and recovery behavior

The patch enables fail-fast startup and bounded reconnect settings. With Streamable HTTP, a temporary server or network failure rejects the affected call; a later call can recover without rebuilding the application process. Credential expiry is different: provide a newly exchanged credential and restart the DSH profile so it rebuilds its Authorization header.

## Production checklist

- Keep app credentials in a server-side secret store and give end-user agents short-lived delegated credentials.
- Grant `mcp.use` and the narrow read/write scopes required by the task.
- Confirm tool discovery before asking a model to act; missing tools normally mean missing scope or sensitive-action policy.
- Preserve correlation IDs and review security/audit events for rejected and mutating calls.
- Pin the tested DSH packages. Re-run initialize, discovery, authorized call, delegated call, revocation, and reconnect tests before upgrading DSH.

Note

MCP does not bypass the API. A tool name, model request, or client-supplied identifier never proves authority; the server re-derives identity and reauthorizes each operation.

Tip

Use MCP for agent intent and the generated OpenAPI/SDK when your software needs a specific one of the complete REST operations.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/deepseek-harness.html).

---
title: "Marketplace service API discovery"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/marketplace-service-apis.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Marketplace service API discovery

Discover installed custom endpoint schemas, download per-app OpenAPI, and let MCP agents plan governed calls.

## In brief

- **REST discovery:** GET /services
- **Projection:** GET /openapi.json
- **Read scope:** appliances.read

Marketplace features can publish custom endpoints without forcing every possible service into the static platform SDK. The Developer API now exposes the installed contract for the selected SaaS app while preserving one governed invocation door.

API callers never receive SQL credentials or database permissions. The server injects the verified SaaS app, tenant account, and user identity and executes only allow-listed stored procedures through `bwhq_developer_api`. That database role has procedure-level `EXECUTE` grants, no table access, no DDL authority, and no ability to drop, create, alter, or directly delete database objects or rows.

## Discover installed endpoint contracts

Call `GET /v1/apps/{saasAppId}/services` with a server-held live credential carrying `appliances.read`. The response includes each installed service key, exact package version and release fingerprint, fixed health state (`Green`, `Yellow`, or `Red`), fixed license state (`Active`, `Suspended`, or `Revoked`), input and output schemas, required permission, execution mode, timeout, availability, and the current tenant user's `canInvoke` result. It never returns container addresses, secret references, database routes, or provider credentials.

## Download the app-specific OpenAPI contract

Call `GET /v1/apps/{saasAppId}/openapi.json` with the same read scope. The result combines the 422-operation base contract with one concrete logical invocation operation for each available installed endpoint. Its OpenAPI response formally declares `ETag`, `X-BuildWithHQ-Contract-SHA256`, and `Cache-Control: private, no-store`; the document also carries `x-buildwithhq-contract-set-sha256`. Generated clients can therefore surface, pin, and detect fingerprint changes.

## Verify discovery authorization

Developer Kit 1.20.70 includes `evidence/installed-service-discovery-policy.sql`, the exact reviewed DROP/CREATE procedure deployed to the golden CustomerCopy database, plus a sanitized JSON evidence record tied to its migration and deployed-definition hashes. Reviewers can verify that discovery first authorizes the calling app/account/user principal, returns only active installations and endpoints whose `SaaSAppId` equals the requested app, and computes `canInvoke` only when the current principal is allowed the endpoint's exact normalized permission key. The receipt also records a rollback-only proof that installs v1, deactivates it, installs v2, and discovers available/invocable v2 without leaking v1. Server and backup topology remain outside the kit.

## Dynamic MCP schemas

`buildwithhq.services.list` requires `mcp.use + appliances.read` and returns the same current endpoint schemas. Agents inspect that result, then use the retained generic `buildwithhq.services.invoke` tool. Invocation separately requires `mcp.use + appliances.invoke`, per-app approval of `installed_services.invoke`, the endpoint permission, an executable exact-fingerprint installation, and secured source records.

Note

appliances.read grants contract visibility only. A schema, path, record ID, canInvoke flag, or per-app OpenAPI operation is never accepted as authorization proof.

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [MCP security model](mcp-tools.html) [OpenAPI versioning](versioning-and-openapi.html)

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/marketplace-service-apis.html).

---
title: "Extensible container services"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/container-services.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Extensible container services

Add custom code in an isolated container, then expose it through declared endpoints the BuildWithHQ runtime can safely invoke.

## In brief

- **Code:** Your language / runtime
- **Integration:** Declared API endpoints
- **Egress:** Sealed or allowlisted

Visual builders are fast until a developer needs something the platform did not predict. BuildWithHQ's container model is the escape hatch: write the custom service you need, then expose its useful behavior through a small, declared endpoint contract.

## The container does not replace the platform

Custom code reaches platform-managed application records through the BuildWithHQ gateway. The gateway validates the caller and endpoint permission, sends the approved payload to the container service, validates the response contract, and records the invocation outcome.

## Endpoint manifest

Each exposed service endpoint can declare:

- a stable endpoint key;
- HTTP method and private route;
- input and output JSON schemas;
- required permission key;
- sync or asynchronous execution mode;
- timeout and payload limits; and
- whether outbound network access is sealed or restricted to an allowlist.

```
{
  "endpointKey": "company.enrich",
  "method": "POST",
  "route": "/v1/company/enrich",
  "executionMode": "sync",
  "requiredPermission": "records.write",
  "inputSchema": {},
  "outputSchema": {}
}
```

## Invocation path

```
POST /v1/apps/{saasAppId}/services/{serviceKey}/endpoints/{endpointKey}:invoke
```

1. A page, workflow, REST action, or MCP tool requests the endpoint by stable key.
2. The platform resolves the installed endpoint and verifies license/health state.
3. Authorization and disclosure checks run before dispatch.
4. The gateway invokes the private container route.
5. The response is validated, safe output is returned, and the invocation result is recorded.

## Why this matters

Developers get normal code and normal libraries when they need them, while the application retains one permission model and one orchestration layer. You do not have to choose between the speed of a visual builder and the freedom of custom architecture.

For the builder-side package and deployment model, see [Appliances and endpoints](../builder-guide/appliances-and-endpoints.html)  and [Container and Postgres](../builder-guide/container-and-postgres.html).

Public service contracts use the BuildWithHQ gateway. Private container addresses remain internal, while the gateway applies authorization, schemas, rate limits, and auditing.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/container-services.html).

---
title: "BuildWithHQ CLI"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/cli.html"
reviewed_at: "2026-09-14"
authority: Official
---

# BuildWithHQ CLI

Use the shipped .NET 10 CLI for profiles, app delivery, templates, services, API clients, workers, AI, and logs.

## In brief

- **Runtime:** .NET 10
- **Principle:** Reviewed API client
- **Automation:** Stable JSON + exit codes

`bwhq` is a thin, scriptable client for reviewed BuildWithHQ HTTP contracts. It uses the same authenticated API surface as other supported developer integrations.

## Representative shipped commands

```
bwhq api info --json
bwhq auth profile add --name production ...
bwhq doctor --json
bwhq app list
bwhq deploy managed --name my-app
bwhq template validate --template-key crm
bwhq service validate --release-file ./release.json
bwhq api-key create --name ci --scope records.read
bwhq worker health
bwhq ai search --query "open work orders"
bwhq logs correlation --log-correlation-id <guid>
```

## Profiles and credentials

A profile stores the exact API origin, SaaS app ID, and an environment-variable or protected absolute-file *reference*. It never stores the bearer credential and there is deliberately no raw `--credential` option. Selection precedence is explicit `--profile`, then `BWHQ_PROFILE`, then the current profile.

## Human and automation output

Interactive commands produce stable text; `--json` produces one compact object on stdout for success or stderr for failure. Correlation IDs and stable exit codes make CI handling deterministic without screen scraping. Shell completion is available for Bash, Zsh, Fish, and PowerShell.

## Account and app credentials are distinct

App-bound Developer API commands use the profile's external API credential. Account-scoped app/deployment commands use the existing Builder control-plane identity supplied through a separate external token reference. The CLI does not silently substitute one for the other.

Note

There are two different CLI concerns: this public developer CLI, and an internal coding-agent/build manifest used to implement the platform itself. The internal build contract is intentionally kept out of the public documentation tree.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/cli.html).

---
title: "Interactive API reference"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/interactive-api-reference.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Interactive API reference

Search and inspect every public BuildWithHQ operation from the current generated OpenAPI contract.

## In brief

- **Contract:** 1.0.0-developer-platform
- **Paths:** 340
- **Operations:** 422
- **Developer Kit:** 1.20.70

This reference reads the same public OpenAPI document used to package Developer Kit 1.20.70. Filter by method, tag, path, summary or operation ID, expand an operation to inspect its inputs and responses, then copy a starter cURL command for your trusted server.

[OpenAPI JSON](../openapi/buildwithhq.json) [OpenAPI YAML](../openapi/buildwithhq.yaml) [Contract manifest and checksums](../openapi/manifest.json) [Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip)

Search operations MethodAll methods TagAll tags

Loading the current public contract...

JavaScript is required for filtering this reference. The complete [JSON](../openapi/buildwithhq.json)  and [YAML](../openapi/buildwithhq.yaml)  contracts remain directly available.

## Use credentials only on a trusted server

The copied command uses an environment-variable placeholder. Keep app credentials and delegated tokens out of browser code. The API still derives tenant, account, user, role and location scope from verified server identity and applies record-level authorization.

## Pin integrations to a version

The stable URLs above always resolve to the current contract. For a reproducible build, use the versioned URLs in the contract manifest or the exact OpenAPI files inside Developer Kit 1.20.70.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/interactive-api-reference.html).

---
title: "OpenAPI, versioning, and SDKs"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/versioning-and-openapi.html"
reviewed_at: "2026-09-14"
authority: Official
---

# OpenAPI, versioning, and SDKs

Keep the API reference, schemas, generated clients, and changelog synchronized from one canonical contract.

## In brief

- **Current spec:** 340 paths · 422 operations
- **Current SDK:** TypeScript connector SDK
- **Breaking changes:** Versioned + announced

The Developer API is generated into a machine-readable OpenAPI 3 contract rather than maintaining endpoint prose, SDK methods, and validators independently. The current document describes 340 paths and 422 operations, including every promoted first-class module route.

## Canonical artifacts

- **OpenAPI** for REST resources, authentication, errors, headers, pagination, and examples.
- **JSON Schema** for application objects, workflow actions, webhook events, MCP tool arguments, and container endpoint contracts.
- **TypeScript connector SDK** and validated quickstart/webhook examples mapped to current operation IDs.
- **Future generated clients or collections** must derive from the same reviewed contract rather than handwritten route lists.

## Versioning

Breaking contract changes belong behind an explicit API version with a published migration path. Additive fields and new resource types can usually remain compatible, but clients should ignore response fields they do not recognize.

## Deprecation

When an endpoint or field must be retired, the API reference should show its replacement, deprecation date, planned sunset date, and migration guide. Response headers can surface the same information programmatically.

## One change, one source

A route change updates implementation annotations and regenerates the canonical OpenAPI/Schema definition. Documentation examples, SDK methods, MCP mappings, and contract tests are validated against operation IDs so they cannot quietly disagree.

Use the [API operating contracts guide](api-operating-contracts.html)  for the concrete version-pin, pagination, filtering, and retry workflow.

Tip

Treat the OpenAPI document as executable product infrastructure. If the implementation and the specification disagree, CI should fail before the change reaches production.

## Current downloadable contracts

[Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [OpenAPI JSON](../downloads/BuildWithHQ-OpenAPI-1.20.70.json) [OpenAPI YAML](../downloads/BuildWithHQ-OpenAPI-1.20.70.yaml)

[Release changes and error-handling guidance](current-api-contracts.html)

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/versioning-and-openapi.html).

---
title: "Progressive loading, fast rows, and exact counts"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/progressive-loading-and-counts.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Progressive loading, fast rows, and exact counts

Render authorized rows immediately, then fill in an independently requested full count without confusing a browse limit with the size of an organization.

## In brief

- **Default:** Fast rows; no exact count
- **Interactive browse:** 5,000 matches
- **Exact count:** Separate opt-in request

Contacts and Global Search now separate interactive row retrieval from full authorized counting. A large exact count must not prevent useful rows, navigation, or unrelated page sections from appearing.

## Progressive loading is not a streaming list endpoint

Each list/count request returns an ordinary JSON response. The native React page progressively fills independent sections as their requests finish; it does not receive individual records over SSE, NDJSON, or WebSocket. MCP Streamable HTTP is a separate transport and does not make these REST list responses streaming.

## Fast defaults and the browse window

`includeTotal` defaults to `false` on Contacts and Global Search. Use `items` and `hasMore` to render and navigate. A list total with `totalIsExact=false` is not the organization's full total. The response's `browseLimit` is currently 5,000: refine the search or filters to reach records beyond that interactive window. The limit does not delete records, reduce storage, or cap the exact count. Other modules retain their own published pagination contracts.

For example, an authorized count of 40,000 should be shown as “40,000 matching records; browse up to 5,000—refine your search,” not “5,000 records.” **Behavior change since 1.20.12:** `hasMore=false` or an empty page on these module routes can mean the browsing window ended, not that every matching record was read. A separate exact count does not lift the row cap. Existing sync/export loops using these module routes must migrate to the Records enumeration path below.

## Search the whole authorized directory, then page the matches

The Contacts API applies `search` before pagination and the browse limit. A contact outside the first 5,000 unfiltered rows can still be found by a matching name, company, email or phone. Keep the same search and filters on every page, and reset `pageNumber` to 1 when they change.

```
GET /v1/apps/{saasAppId}/modules/contacts?search=smith&pageNumber=1&pageSize=50
GET /v1/apps/{saasAppId}/modules/contacts?search=smith&pageNumber=2&pageSize=50
GET /v1/apps/{saasAppId}/modules/contacts/count?search=smith
```

These are authenticated trusted-server requests. URL-encode search values. The count reports all authorized matches for “smith”; if that search itself has more than 5,000 matches, make it more specific. Page-number traversal is not a frozen snapshot: concurrent edits can shift rows between pages.

## Enumerate every authorized contact

For full contact enumeration, use `POST /v1/apps/{saasAppId}/objects/contacts/records/search` with `records.read`, a body such as `{"page":1,"pageSize":100,"sort":"created_asc"}`, and follow that operation's `hasMore`. Increment `page` (not `pageNumber`) while keeping filters and identity unchanged. This generic Records operation has no 5,000-row cap. Its response contains `records`, common record metadata and permitted custom fields, not native Contacts rows.

For native email/phone fields, hydrate returned IDs through `GET /v1/apps/{saasAppId}/modules/contacts/{recordId}` with `modules.contacts.read`. Each read reauthorizes access; bound concurrency and handle records removed or access revoked between requests. The kit README and `examples/enumerate-contacts.mjs` provide the SDK iterator and executable tests.

This is numbered-page enumeration, not a snapshot/export job or incremental change feed. Concurrent writes or authorization changes can shift pages and cause omissions; a stable sort and deduplication alone do not fix that. Use a quiescent source window and reconcile completeness when required. Deep paging and per-record hydration have their own costs.

## Dedicated count endpoints and scopes

| Public route | SDK method | Required scope |
| --- | --- | --- |
| `GET /v1/apps/{saasAppId}/modules/contacts/count` | `contactsCount` | `modules.contacts.read` |
| `GET /v1/apps/{saasAppId}/modules/global-search/count` | `globalSearchCount` | `modules.global-search.read` |

Native authenticated tenant routes are `/api/modules/contacts/count` and `/api/modules/global-search/count`. Counts return `contractVersion`, `totalRecords`, `totalIsExact=true`, and `browseLimit`. They do not accept paging arguments. Copy the same supported filters from the row request: Contacts uses `search`, `contactType`, repeated `contactTypeId`, and `locationId`; Global Search uses its declared `query`, `moduleKey`, and `locationId`.

### Use rows and counts separately

Omit `includeTotal` on list requests. **Pre-launch breaking change, live in server 1.20.21:** legacy `includeTotal=true` requests return HTTP 400 with `contacts_count_endpoint_required` or `global_search_count_endpoint_required`. The normal validation envelope includes `code`, a safe `error` message directing you to the matching count endpoint, and `correlationId`. Do not retry the rejected list request unchanged: fetch rows without the parameter and call the dedicated count endpoint with the same filters and identity. Developer Kit 1.20.18 removes the parameter from OpenAPI and the SDK; older clients explicitly sending `false` remain accepted. An authenticated public check verified both errors, both count endpoints and omitted/false lists on September 23, 2026.

Render rows independently. If the separate count request times out or is unavailable, retain the rows with `totalIsExact=false` and show “Total temporarily unavailable,” not zero or a failed page. A successful count can update the displayed total without refetching rows. The read-only Global Search MCP tool uses the fast default. MCP access separately requires `mcp.use` and the tool's module scope; a REST read credential alone does not grant MCP discovery.

## Counts obey the same security boundary as rows

A count is limited to the verified app, organization, user, DataRole, record participation and location visibility. It is not a tenant-wide aggregate. Supplying an `appAccountId` or `userId` cannot replace the verified identity. A supported location filter can narrow an authorized set, never expand it. No visible records produces zero; denial or a failed request must not be displayed as zero. A read-only credential can count but cannot write.

## Use the executable SDK example

Kit 1.20.70 includes `examples/progressive-contacts.mjs` and its offline regression tests. Run the SDK on your trusted backend and forward authorized results through your existing application channel. The helper starts the two requests together and invokes independent callbacks; it does not expose a new BuildWithHQ endpoint.

```
import { loadContactsProgressively } from "./examples/progressive-contacts.mjs";

const abort = new AbortController();
const work = loadContactsProgressively(api, {
  filters: { search: "Ada" }, pageSize: 50, signal: abort.signal,
  onRows: page => sendAuthorizedRowsToYourView(page),
  onCount: count => updateYourViewTotal(count.totalRecords),
  onCountError: () => showYourViewCountUnavailable(),
});
// Your application supplies the callbacks above; rows do not wait for count.
await Promise.all([work.rows, work.count]);
// On navigation, identity or filter changes: abort.abort().
```

```
node --test examples/progressive-contacts.test.mjs
```

Important

App credentials belong on trusted servers, never in browser bundles, page JSON, local storage, prompts or logs. Use the documented delegated-user flow when acting as an end user.

## Cache and consistency boundaries

The native UI keeps display-count snapshots in session memory with a 60-second freshness limit, bounded requests and invalidation after relevant mutations/session changes. It is not a permanent session total and there is no server-side count cache. Rows and count are separate reads, not one transactionally consistent snapshot; concurrent writes can make them differ temporarily.

For your own cache, include the verified identity and every filter, clear it on logout/account/permission changes, and discard late responses from an abandoned view. Do not share counts across organizations or credentials. Keep rows usable if the count fails; offer a bounded retry rather than issuing a count for every page. Counts are int64 in the API: JavaScript clients must reject unsafe integers or use a lossless parser rather than silently round an exact total.

## Operational expectations

Exact counts can still be expensive. Give them a separate timeout/error state, bound concurrency, honor `Retry-After`, and capture the server-issued correlation ID. Local load measurements are not a production SLA. Establish latency targets, monitoring and capacity for your actual data and authorization shape before launch.

Next: [pagination and retries](api-operating-contracts.html), [enterprise integration readiness](go-live-checklist.html), and [contract/version pinning](versioning-and-openapi.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/progressive-loading-and-counts.html).

---
title: "Pagination, filtering, rate limits, and versioning"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/api-operating-contracts.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Pagination, filtering, rate limits, and versioning

Implement list traversal, server-side filters, 429 recovery, and contract pinning from the exact OpenAPI operation.

## In brief

- **Module lists:** pageNumber + hasMore
- **Organization lists:** afterAppAccountId cursor
- **Rate limits:** 429 + required Retry-After

BuildWithHQ uses one public v1 API with operation-specific list contracts. The OpenAPI operation defines its parameters, defaults, bounds, response shape, credential class, and scopes. A client should not impose one pagination or filter shape on routes that publish different contracts.

[OpenAPI and SDKs](versioning-and-openapi.html) [Limits and idempotency](limits-and-quotas.html) [Download the executable example](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip)

## Use the declared pagination family

| List family | Request | Continue with | Stop when |
| --- | --- | --- | --- |
| Most first-class modules | `pageNumber`, `pageSize`, and declared filters | Increment `pageNumber` | `hasMore` is false |
| Organization discovery | `afterAppAccountId`, `pageSize`, optional `search` | Return `nextAfterAppAccountId` as the next cursor | The next cursor is absent |
| Tenant-user directory | No paging or cursor parameters | No follow-up request | The complete `users` array is returned |
| Bounded history/projection routes | The operation's documented `limit` or other bound | Only as that response declares | The operation-specific condition is reached |

Module list envelopes can report `pageNumber`, `pageSize`, `totalRecords`, `totalPages`, `totalIsExact`, `hasMore`, and `items`. Drive traversal with `hasMore`. Treat a total as exact only when `totalIsExact` is true.

Contacts and Global Search default to `includeTotal=false` and return a `browseLimit` of 5,000. Request an uncapped authorized total through the dedicated count endpoint, without blocking row rendering. See [progressive loading and exact counts](progressive-loading-and-counts.html)  for routes, scopes, cache boundaries and the executable SDK example.

**Sync/export migration:** a module-list `hasMore=false` at this cap does not prove a complete directory. For all authorized Contacts records use `POST /v1/apps/{saasAppId}/objects/contacts/records/search` with `page`, `pageSize` (1–100) and a fixed sort, following that operation's continuation. The linked guide explains its generic record shape, native-field hydration and lack of snapshot guarantees.

The tenant-user list returns the whole authorized organization directory in one response. Its exact `totalCount` equals the length of `users`; each row includes DataRole and location counts and assignments. Zero selected locations means all locations, not no access. Do not send legacy page or cursor parameters. No per-organization user ceiling is enforced today, so response size grows with users and assignments. The expected case is a few hundred users; large-directory limits or streaming remain pre-launch scale work. A dependency failure returns 503, not an empty list.

## Book an eligible tenant user

Call `GET /v1/apps/{saasAppId}/modules/reservations/assignees` with `reservationProductId` and `startUtc` together, plus an optional `locationId`. Choose an item from `items` and send its `optionId` as `assignedUserId` to Reservation purchase or reschedule; `lookupId` identifies the lookup contract and is not a user ID. The server rechecks eligibility and capacity on write. On `409 reservations_conflict`, refresh the Reservation and assignee choices. There is no generic `/modules/reservations/lookups` route; use `/products` and `/assignees`.

## Filter before data reaches the browser

Send only filters declared for the operation, such as `search`, `status`, `locationId`, or a module-specific state. Omit an unused filter. The server applies verified app, account, user, DataRole, Location, and permission scope before the requested filter. IDs and cursors select targets inside that boundary; they do not grant access.

## GoClaw authority errors in the tenant runtime

For the signed-in tenant route `PUT /api/goclaw/agents/{goClawAgentId}/authority`, handle `400 goclaw_authority_invalid_request` by correcting the request, `403 goclaw_authority_forbidden` as a permission denial, and `404 goclaw_authority_not_found` by refreshing the authorized agent list. The route is not an app-scoped Developer API operation. Kit 1.20.70 includes the exact mapping in `catalog/tenant-runtime-error-codes.json`; framework-level model validation can also return 400 with a different response shape.

## Handle tenant page and workflow status failures

The authenticated tenant page-save route `POST /api/runtime/pages/{pageKey}/revisions/save` requires the verified account owner and the builder's tenant-edit policy. A missing page returns `404 page_revision_not_found`; a protected page returns `403 page_revision_not_editable`. Require `report.Saved=true` even when HTTP is 200, and preserve the E020 edit-lease, E021 ID-loss acknowledgement and E022 stale-version reports.

For `PUT /api/inbox/items/{inboxItemId}/human-state`, keep the current `expectedActivityVersion`. A pending workflow approval cannot be resolved, closed, snoozed or moved to WaitingCustomer: the server returns `400 inbox_request_invalid` without changing state. Complete the authorized workflow decision first; older stranded items can be reopened. Stale revisions return `409 inbox_stale_context`. IDs and refreshes never grant edit or approval authority. Kit 1.20.70 records these codes in `catalog/tenant-runtime-error-codes.json`.

## Honor the rate-limit contract

Every published `429 Too Many Requests` response declares a required `Retry-After` header containing whole seconds with a minimum of one. Wait that long, then retry within a bounded attempt count. Use capped exponential backoff with jitter for transient 502, 503, and 504 responses.

```
const waitSeconds = Number(response.headers.get("Retry-After"));
if (response.status === 429 && Number.isInteger(waitSeconds) && waitSeconds >= 1) {
  await new Promise(resolve => setTimeout(resolve, waitSeconds * 1000));
}
```

GET and HEAD requests can be retried safely. Retry a write only when its operation supports an idempotency key or explicitly defines repeat-safe behavior. Reuse the same key and payload. Preserve the API error `correlationId` when the bounded attempts end.

## Pin and update the contract

Generate against the OpenAPI file in the immutable Developer Kit. For an app with marketplace services, call `GET /v1/apps/{saasAppId}/openapi.json` and pin `X-BuildWithHQ-Contract-SHA256` or the matching document fingerprint. Regenerate when it changes. Clients must ignore additive response properties they do not recognize; breaking changes require an explicit API version and migration guidance.

## Run the offline example

The Developer Kit includes `examples/api-client-policy.mjs` with a bounded request loop, numbered-page iterator, and organization cursor iterator. Its test uses mocked HTTP responses and needs no credential:

```
node --test examples/api-client-policy.test.mjs
```

Note

Page-size bounds and allowed filters belong to each OpenAPI operation. Never copy one route's maximum, default, status values, or cursor semantics into another client method.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/api-operating-contracts.html).

---
title: "Limits, rate limits, and idempotency"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/limits-and-quotas.html"
reviewed_at: "2026-10-31"
authority: Official
---

# Limits, rate limits, and idempotency

How clients should handle quotas, throttling, payload boundaries, retries, and safely repeated writes.

## In brief

- **Throttling:** 429 + Retry-After
- **Writes:** Idempotency where supported
- **Large work:** Async operations

Developer limits should be explicit and observable. The API must fail clearly when a client exceeds a rate, payload, plan, storage, or execution boundary; it should never silently drop records or truncate a mutation.

## Rate limiting

When a caller exceeds its current request allowance, the gateway returns `429 Too Many Requests`. Honor `Retry-After`, which can contain nonnegative whole seconds or an HTTP-date. Wait at least that long, add jitter, and bound retry attempts and total waiting time. Missing or malformed retry hints do not authorize an immediate retry loop.

The checked-in Developer Gateway defaults to **60 requests per 60-second window** for each verified caller partition. This is an outer traffic limit, not 60 requests for every endpoint or an entitlement to unlimited writes. Module operations also have separate per-caller, app and module limits:

| Module operation class | Default requests per minute |
| --- | --- |
| Read | 60 |
| Write | 30 |
| Search | 30 |
| File transfer | 20 |
| AI | 10 |
| Sensitive write | 10 |

Operators can configure these defaults. A request must pass every applicable limit; splitting calls across module routes does not remove the outer limit. Follow the actual response headers and current environment contract. Pace list/detail traversal and bound concurrency. A pagination endpoint is not a bulk-write endpoint; use only operations actually declared by the pinned OpenAPI contract.

## Idempotent writes

Use an idempotency key only when the exact operation documents one; adding an invented header does not make a write safe to repeat. Preserve the selected record scope and exact concurrency revision. After a network failure or an unusable write receipt, inspect the authoritative record or documented operation status before deliberately submitting again. Never automatically repeat a create, payment, invitation, archive, or webhook retry.

## Plan and resource limits

Some limits are application or subscription entitlements rather than traffic controls — for example storage pools, AI budgets, or feature access. Those failures should use structured error codes and include a safe explanation of the resource that needs attention.

## Payload and execution limits

Large imports, exports, and long-running actions should move to asynchronous operation resources. Container-backed endpoints also have explicit execution and payload boundaries so a custom service cannot tie up the gateway indefinitely.

The current record-search contract bounds `pageSize` to 1–100 and query text to 400 characters. Every other request/list bound is defined by its OpenAPI schema or environment response; clients must validate against that contract instead of assuming the record-search values apply globally.

See [Pagination, filtering, rate limits, and versioning](api-operating-contracts.html)  for copyable request and traversal behavior.

## SDK and Kit recovery

The repository SDK candidates retry eligible reads once by default, only after a valid 429 hint. Connector, delegated runtime, design, generated module and Builder platform clients retry GET/HEAD only; the separate Headless SDK also recognizes its explicitly read-only POST record search. Other methods are never automatically repeated. Each client has its own cooldown, at most 60 seconds of automatic waiting and up to 250 milliseconds of added jitter by default. Longer server delays are surfaced intact instead of shortened. Cancellation stops the waiting caller. Other HTTP errors and network failures are not automatically retried.

For cross-origin browser integrations, the API must expose both `Retry-After` and `Date` through its reviewed CORS policy. The SDK can use the response Date to interpret an HTTP-date retry hint against the server clock. Neither header is a [CORS-safelisted response header](https://fetch.spec.whatwg.org/#cors-safelisted-response-header-name); seeing one in the browser's network inspector does not mean JavaScript can read it. Verify the deployed policy before relying on this behavior. The repository Gateway change is a source candidate until separately activated.

The Design client remains server-only and requires its documented Builder credential. Use the reviewed delegated-user flow for browser-capable clients; retry support does not make a long-lived app or Builder key safe to embed in a browser.

Writes are never automatically repeated. The reference Kit preserves the draft and displays a countdown; finishing the timer does not submit the form. If a response was lost or malformed, the uncertain-write lock remains until the user refreshes and inspects authoritative state. This SDK/Kit behavior is staged repository work; the published Developer Kit is unchanged until a new reviewed release is published.

The repository reference client's countdown follows elapsed time from response-header receipt, including time spent reading a slow response body. Changing the computer's wall clock does not shorten or extend that wait. Timer completion still requires a deliberate action, and an uncertain-write lock still requires explicit read recovery.

Note

Traffic rates, burst rules, retention, and plan entitlements can vary by environment or subscription. Read server responses and current plan metadata; never encode an unpublished numeric allowance as permanent client behavior.

---

Capability review: 2026-10-31. [View the canonical guide](https://support.buildwithhq.com/api/limits-and-quotas.html).

---
title: "Integration go-live checklist"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/go-live-checklist.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Integration go-live checklist

A practical review for credentials, scopes, retries, webhooks, observability, test isolation, and operational ownership.

## In brief

- **Goal:** Least privilege + recoverability
- **Evidence:** Correlation IDs + pinned API contract
- **Owner:** Named operator

Use this checklist before an integration handles customer data or performs production mutations. Passing a happy-path request is not enough.

## Identity and secrets

- Create a dedicated API client for the integration and environment.
- Remove scopes that the exercised operation inventory does not require.
- Store credentials and connector secret references in an approved secret manager.
- Document rotation and emergency revocation, then test both.
- Verify the returned auth context matches the intended SaaS app during startup.

## Requests and recovery

- Bound timeouts, concurrency, pages, and retry attempts.
- Retry only safe or idempotent operations and honor `Retry-After`.
- Test duplicate webhook delivery, out-of-order events, stale signatures, and dead-letter retry.
- Handle `401`, `403`/safe `404`, `409`, `422`, `429`, and `5xx` deliberately.
- Use documented status, retry, recovery, and correlation workflows during an outage.

## Compatibility and observability

- Validate examples/SDK calls against the current OpenAPI operation IDs.
- Pin the Developer Kit version and OpenAPI checksum used to generate or validate the integration.
- Log operation, duration, status, app ID, and correlation ID without secrets or raw sensitive bodies.
- Create alerts for sustained authentication failures, rate limiting, webhook dead letters, and failed async jobs.
- Name a human owner and escalation path for each integration, inbound endpoint, webhook subscription, and connector.

## Environment proof

Exercise the exact production origin and credential only through an approved deployment check. A successful local or staging contract test does not prove DNS, certificates, rate configuration, external callbacks, or production secret delivery.

## Enterprise release evidence

- Prove cross-organization and cross-app denial for both rows and counts, including forged identity selectors, restricted locations, revoked credentials and read-only write denial.
- Pin the kit checksum and app-specific OpenAPI fingerprint; test backward compatibility and contract readiness for every routed database before runtime activation.
- Document durable file/log storage outside release directories, backup ownership, a tested restore procedure, rollback verification and named on-call responsibility.
- Set and measure your required availability, latency, recovery-time and recovery-point targets. A successful battle test is not an uptime guarantee, recovery certification or compliance attestation.
- Confirm retention, deletion, data residency, external-provider handling and incident escalation for your deployment and agreement; do not infer them from an API feature list.
- Track unavailable or planned capabilities explicitly. Installed-service Tasks and Skills are current; workflow/AI-job task projections, Builder Account MCP, Developer VM MCP, MRTR and an MCP OAuth authorization server must not be inferred from those capabilities.

Tip

Keep a small runbook beside the integration: purpose, app ID, scopes, secret owner, endpoints, dashboards, contract version, rotation steps, and rollback switch.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/go-live-checklist.html).

---
title: "Email and SMS support lanes"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/support-lanes.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Email and SMS support lanes

Manage organization-owned receiving channels through a secured API and editable React page.

## In brief

- **Configuration owner:** Tenant organization owner
- **Native module:** Universal Inbox
- **Developer Kit:** 1.20.70

Support lanes organize incoming email and SMS within Universal Inbox. Conversations and messages remain the native source records; lanes do not create a second ticket database.

## Organization configuration, editable presentation

The tenant organization owner opens **Admin → Support lanes → Open support lane manager**. The SaaS administrator must first install the supplied `pages/support-lanes.json` as `SupportLanes` and assign that page to the appropriate User Type through the normal page/menu lifecycle. The link uses the secured page resolver; a missing or inaccessible page does not produce a working link. This is not a builder-admin channel setup screen.

Kit 1.20.70 includes editable `react/support-lanes/` source: manager, workspace provider, toolbar, list, editor, searchable picker, HTTP client and CSS. Builders can change layout, labels and styling without acquiring permission to configure a customer's channels. Hosted pages compose registered components; page JSON does not execute uploaded JSX. Installed snapshots and tenant forks require explicit adoption of later template versions.

## Day-to-day lifecycle

Create, view, edit and retire lanes. Each lane can attach one existing receiving email channel, one existing SMS number and an optional existing GoClaw worker in the same organization. A channel belongs to at most one lane. The manager does not buy phone numbers or accept provider secrets. SMS is messaging, not a voice-call channel.

There is no fixed lane-count limit. Follow `nextAfterId` while `hasMore` is true. List and option pages are bounded; the final cursor is null. Channel searches expose only eligible organization-owned options.

Attaching a receiving channel enables ticketing. Preserve revision strings and the channel's exact seven-digit UTC timestamp. On HTTP 409, reload and review rather than blindly retrying. Retirement requires explicit detach confirmation, retains tickets and audit history, and returns future intake to existing routing. Assigning GoClaw grants no additional record, DataRole, location, AI-read or action authority.

## Public API

Prefix every route with `/v1/apps/{saasAppId}`. Use the existing `modules.universal-inbox.read` or `modules.universal-inbox.write` scope as appropriate. The verified runtime user must also satisfy the organization-owner check; an app ID or scope alone is not authorization.

- `GET /inbox/support-lanes` — paginated lanes.
- `GET /inbox/support-lanes/options?kind=email|sms|goclaw` — scoped, searchable options.
- `GET /inbox/support-lanes/{laneId}` — lane detail.
- `POST /inbox/support-lanes` — create.
- `PUT /inbox/support-lanes/{laneId}` — revision-checked update.
- `POST /inbox/support-lanes/{laneId}/retire` — explicit, revision-checked retirement.

Foreign lane/channel identifiers are not disclosed; unauthorized access fails closed. Read-only credentials cannot mutate configuration. Use the shipped OpenAPI and generated SDK for exact request fields and response types.

## Delivery and release boundaries

Authenticated inbound email and SMS enter the existing ingestion pipeline and route to their attached lane. Duplicate provider deliveries preserve ticket identity. Inbox remains polling-based; this release does not promise instant push delivery or a new SSE list endpoint. See [progressive loading and counts](progressive-loading-and-counts.html)  for the separate rows-first loading behavior.

Publication requires the matching live server and routed database contracts. External DeepSeek Harness approval evidence is a separate CLI/MCP launch requirement, not evidence of support-lane delivery.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/support-lanes.html).

---
title: "Outside form submissions"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/outside-form-submissions.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Outside form submissions

Configure tenant-owned form endpoints and receive server or browser submissions in Universal Inbox.

## In brief

- **Configuration owner:** Tenant organization owner
- **Submission modes:** Server secret or public browser
- **Record boundary:** Personal or DataRole + optional location

An outside form endpoint accepts a JSON or URL-encoded POST from a site or external server and creates an organization-scoped source record plus a Universal Inbox item. Each endpoint is configured by its tenant organization owner. The incoming item receives the configured **Personal** owner or **DataRole** and optional location at creation; the sender cannot choose or override that visibility. Inbox is the attention layer, not a separate form-record database.

You can use any existing HTML form or trusted server form; BuildWithHQ does not require a form builder or a predefined field schema. Submit ordinary named fields, then open the resulting Universal Inbox item to see a secured table of each submitted key and value. The original submission remains a native source record. A user can ask GoClaw to propose a Contact or other action from it, subject to the normal permission and approval policy; the POST itself does not automatically create a Contact.

## Configure an endpoint

The owner chooses a unique `endpointKey` (lowercase letters, digits, period, underscore or hyphen; at most 100 characters), display name, mode, and target. Exactly one target is required: `ownerUserId` for Personal, or `targetDataRoleId` for a shared role. `locationId` is optional for role targets. A public-browser endpoint also needs one exact HTTPS `allowedOrigin`; server-secret endpoints must not set it. A disabled endpoint rejects new submissions. Updating requires the current `expectedRevision`; a conflict means reload before retrying.

The tenant UI uses `GET /api/outsideformsubmissions/endpoints`, `POST /api/outsideformsubmissions/endpoints`, and `PUT /api/outsideformsubmissions/endpoints/{endpointId}` on the tenant hostname. The public Developer API exposes the corresponding routes under `/v1/apps/{saasAppId}/outsideformsubmissions`, with `GET /endpoints`, `POST /endpoints`, and `PUT /endpoints/{endpointId}`. Management requires a **delegated active tenant-owner** credential with `outside-forms.manage`; a server-held app credential, scope alone, or a supplied owner ID does not confer ownership. The list is bounded to 100 entries per page. Create does not accept `expectedRevision` or `rotateSecret`; those are update-only controls. `GET /browser-challenge` returns the public Turnstile site configuration, and `GET /{submissionId}` reads one authorized submission. A server secret appears only on server-mode creation, explicit rotation, or changing a browser endpoint into server mode; list and ordinary update responses never include it. A lost secret cannot be read back and must be rotated.

## Server-to-server POST

Send to `https://{tenant-host}/api/outsideformsubmissions/server/{endpointId}` with `Content-Type: application/json` or `application/x-www-form-urlencoded`, a fresh GUID `Idempotency-Key`, and the `X-Outside-Form-Secret` header. The 64-character secret is returned only when created or explicitly rotated. Store it server-side; never embed it in HTML, JavaScript, or a public repository. A first accepted submission returns 201; an idempotent replay returns 200 with the same receipt.

## Public-browser POST

Send to `https://{tenant-host}/api/outsideformsubmissions/browser/{endpointId}` from the endpoint's configured exact HTTPS origin. Include a GUID `Idempotency-Key` and a fresh Cloudflare Turnstile token in `X-Turnstile-Token` (or `cf-turnstile-response` for an HTML form). The widget uses action `outsideformsubmissions`. The server verifies the token, hostname, action, and allowed origin; a missing provider configuration or invalid challenge fails closed. Operators must configure the site key, server-side secret, and permitted form hostname before browser submissions can work. CORS preflight allows only the configured origin and submission headers.

## Limits and security

Payloads are capped at 64 KiB, JSON depth four, and 100 form fields. Form keys cannot set tenant, user, DataRole, location, or other authorization identity. Do not treat a successful POST as permission to read the created record: normal secured-record procedures still enforce tenant, DataRole/Personal, and location access. The API returns safe error codes and a correlation ID; do not log secrets or challenge tokens.

The Developer Kit includes the management operations and these submission instructions, but public submissions go to the *tenant hostname*, not `api.buildwithhq.com`. This separation lets external servers use a narrow secret and browsers use an anti-spam challenge without exposing a Developer API key.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/outside-form-submissions.html).

---
title: "Current API contracts and error handling"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/current-api-contracts.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Current API contracts and error handling

Kit 1.20.70: exact public API contracts, SDK packaging, webhook errors and shared AI routes.

## In brief

- **Kit:** 1.20.70
- **App-scoped operations:** 422
- **Builder operations:** 129
- **Native module operations:** 295
- **Authority:** Verified server identity

[Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [OpenAPI JSON](../downloads/BuildWithHQ-OpenAPI-1.20.70.json) [OpenAPI YAML](../downloads/BuildWithHQ-OpenAPI-1.20.70.yaml)

## Pin a contract version

Developer Kit 1.20.70 contains 422 public operations, including 295 native module operations. The JSON and YAML downloads are the same contracts packaged in the ZIP. Keep the ZIP checksum with your integration release, generate clients from that version, and review changed response handling before upgrading.

## Developer Kit 1.20.65: Contacts sorting and applied-order echoes

The Contacts list accepts optional `sortBy` (`name`, `companyName`, `updatedUtc`) and `sortDirection` (`asc`, `desc`). Responses echo the applied values. Defaults remain `updatedUtc` descending; record permissions and the browsing limit are unchanged.

The matching Gateway is deployed. Fresh authenticated acceptance checks all six sort echoes through the public HTTPS binding on the owned test tenant. The exact ZIP-bound offline and live report is beside the download; this evidence does not claim unrelated provider or tenant workflows were exercised.

## Developer Kit 1.20.64: review corrections, generated contracts and SDK bounds

This release corrects the earlier Company News and Inbox reply prose using the archived contracts. Child-creation statuses, request-body policies and DELETE concurrency tables now come from the packaged OpenAPI, and the release gate rejects stale tables and contradictory current prose. Published changelog sections stay intact; corrections are recorded in the new entry.

The SDK now checks declared page-size bounds before requests for support-lane lists and options, record-graph search and reservation assignees. The kit includes an evidence index, the previous release's accepted report and live summary, and labeled prepublication receipts for the current payload. The final ZIP-bound report and checksum remain beside the download.

Unknown-field rejection from 1.20.63 remains in force for its tightened requests. The request-fields guide separately documents Calendar and Dynamic records' remaining open custom-field entry handling; those exceptions do not grant permission to create arbitrary field definitions.

## Developer Kit 1.20.63: strict request fields and custom-field guidance

Breaking request-contract change: the tightened Chat, Conversations, Discussion, News and Files requests reject unknown fields with HTTP 400 instead of silently ignoring them. File uploads reject extra form fields and file-part names. The error identifies the field, preserves a correlation ID and does not echo the submitted value.

Some record types support administrator-configured custom fields. Where the operation declares `dynamicFields`, submit configured values through that input on the supported record create/edit route. Files upload uses the declared `DynamicFieldsJson` form input. Extra fields on messages, reactions, favorites and attachment links do not create custom fields. Configuration, visibility, permissions and revision requirements still apply.

All 19 previous open-body contract warnings are resolved. Publication now requires fresh live HTTP and real Chrome checks tied to the exact kit ZIP, alongside the offline contract, SDK, test and mutation gates. See the included `docs/REQUEST-FIELDS.md` and the exact gate report before upgrading.

## Developer Kit 1.20.62: restored Mail Reader and live API calibration

The Mail Reader list, message detail, favorite and mark-read routes are restored after SQL security checks and live API and Chrome verification. Mailbox configuration, credentials, compose/send and archive remain outside the public Mail Reader API. Chat, Conversation and Discussion history clients validate paired cursors and declared page-size bounds before sending a request.

Response contracts now match live child creation status 201, attention presentation wrappers, optional response objects and validation/not-found/conflict errors. Regenerate clients and review `CHANGELOG.md` before upgrading. Preserve every revision string exactly. The archive passed the release gate on both supported Node versions and all 15 SDK guard mutation checks. [Download its exact release-gate report](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.62.zip.gate.json); the report documents remaining contract warnings and does not replace testing your integration.

## Developer Kit 1.20.61: historical release and corrections

This release added bounded Chat, Conversation and Discussion history and board topic paging, alongside nullable dynamic-field and opaque revision declarations. It also removed four previously published Mail Reader operations: `GET /v1/apps/{saasAppId}/modules/mail-reader`, `GET /v1/apps/{saasAppId}/modules/mail-reader/{recordId}`, `PUT /v1/apps/{saasAppId}/modules/mail-reader/{recordId}/favorite` and `PUT /v1/apps/{saasAppId}/modules/mail-reader/{recordId}/read`. Those were breaking removals, omitted from the original notes; version 1.20.62 restores them. Company News deletion already declared HTTP 409 in the published 1.20.61 contract. The contrary 1.20.62/1.20.63 errata is corrected in the 1.20.64 changelog; the earlier ZIP sections remain preserved.

The original 1.20.61 archive passed the release-gate implementation used at publication. A later audit found checks that were too weak for removal disclosure, revision conflict declarations, immutable changelog history and cursor coverage. [The original report](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.61.zip.gate.json)  is preserved as historical evidence; it does not mean 1.20.61 passes the hardened policy. The archive and its checksum remain unchanged.

## Developer Kit 1.20.60: preserve exact revision strings

Pre-launch request-contract and response-contract changes: timestamp revision fences and their source response fields are opaque strings in the OpenAPI and SDK. This includes Knowledge articles, Reservations, reservation products and tenant-user updates and deactivation. Preserve every fractional digit and the returned timezone marker, including its absence. Send the exact returned `updatedUtc`, `modifiedUtc` or `revisionUtc` value in the matching `expectedUpdatedUtc` or `expectedRevisionUtc` field. Never round-trip a revision through JavaScript `Date`. Refresh and reconcile a conflict before retrying.

The archive includes reviewed operation-scope metadata, declared error codes and aligned MCP revision and ID schemas. Its extracted contents passed the offline release gate, both Node 22.22.2 and 24.19.0 test/build runs, and all seven SDK guard mutation checks. See `CHANGELOG.md`, `docs/API-OPERATING-CONTRACTS.md` and `docs/DELETE-CONCURRENCY.md` inside the kit for affected operations and compatibility guidance.

These are kit validation results. Matching server changes need deployment and live verification. The kit does not establish deployed revision enforcement, unknown-field rejection, webhook retry ID typing or SQL error mappings. Communications child bodies remain open where rejection has not been proved; five child POST contracts retain HTTP 200 pending live evidence. Remote DSH journey evidence and publication of the private `@buildwithhq/page-runtime` package remain open.

Version 1.20.60 is a new immutable archive. The first 1.20.59 archive was superseded by its authoritative rebuild; both SHA-256 values are recorded in the kit changelog. Keep each archive with its own adjacent `.sha256` file.

Every public operation now has a concise OpenAPI summary for API explorers and generated clients. The summaries describe route intent; the operation description, request schema, response schema and verified authority remain the contract for implementation.

The API route map now reflects corrected route discovery, including combined attributes, multiple aliases and absolute paths. Discovery corrections preserve existing operation scopes. An operation appearing in a catalog does not mean that its provider is configured for every app.

## Webhook responses

Webhook delivery history now supports keyset paging. Request 1–100 rows with `pageSize`; if `hasMore` is true, send both returned `nextBeforeCreatedUtc` and `nextBeforeDeliveryId` as the next request's `beforeCreatedUtc` and `beforeDeliveryId`. The cursor ID and each item's `deliveryId` and `eventId` are decimal strings so JavaScript does not round a SQL BIGINT. Pass the string delivery ID directly to `retryWebhookDelivery`. Omit both cursor fields on the first page. The authorized account and app-scope filters apply to each page, and the SDK exposes `listWebhookDeliveriesPage`.

The six tenant-organization Snowflake operations cover configuration, connection testing, enable/pause, manual export and hosted scheduling. Organization owners and authorized Builder support credentials can configure Snowpipe Streaming through the same scoped public API. [Setup, permissions and current availability](tenant-snowflake.html).

## Tenant payment lifecycle contracts

The kit includes typed public methods for tokenized payment-method registration and detail, revision-fenced default/revoke, and lease-version-fenced pending-charge cancellation. Payment-method writes use the sensitive-write budget. Send the exact `expectedUpdatedUtc` or `expectedLeaseVersion` returned by the latest read, refresh after HTTP 409, and never collect raw card data through these routes. The verified credential and secured procedures recheck app, organization, user, DataRole, location, customer and payable-record scope.

Use the declared response statuses below. Validation errors explain the field or position to correct; conflicts require resolving the reported state. Dependency failures may return 503, and unexpected failures return 500. An explicitly retryable dependency error includes `Retry-After`. Do not blindly retry mutations: preserve documented idempotency and revision checks.

| Operation | Declared responses |
| --- | --- |
| `GET /v1/apps/{saasAppId}/webhook-deliveries` | 200, 400, 401, 403, 500, 429, 409, 422, 503 |
| `POST /v1/apps/{saasAppId}/webhook-deliveries/{deliveryId}/retry` | 200, 400, 404, 401, 403, 500, 429, 409, 422, 503 |
| `GET /v1/apps/{saasAppId}/webhook-event-types` | 200, 401, 403, 500, 429, 409, 422, 503 |
| `GET /v1/apps/{saasAppId}/webhooks` | 200, 401, 403, 500, 429, 409, 422, 503 |
| `POST /v1/apps/{saasAppId}/webhooks` | 201, 401, 403, 500, 429, 409, 422, 503, 400 |
| `PUT /v1/apps/{saasAppId}/webhooks/{subscriptionId}` | 200, 404, 401, 403, 500, 429, 409, 422, 503, 400 |
| `POST /v1/apps/{saasAppId}/webhooks/{subscriptionId}/rotate-secret` | 200, 400, 404, 401, 403, 500, 429, 409, 422, 503 |

Error JSON uses `error` for the safe explanation, `code` for the stable identifier and `correlationId` for troubleshooting. Include the correlation ID when requesting help. Do not put credentials, secrets or customer payloads into diagnostic messages.

## CompanyIQ and OpsAtlas

These solutions share the existing app-scoped AI operations: `GET /v1/apps/{saasAppId}/ai/status`, `POST /v1/apps/{saasAppId}/ai/sources/records/{recordId}/ingest`, and `POST /v1/apps/{saasAppId}/ai/search`. Their availability depends on the caller's permissions, record visibility and configured AI providers. Separate solution-specific aliases are not required.

## Installed services and ownership

Use `GET /v1/apps/{saasAppId}/services` and `GET /v1/apps/{saasAppId}/openapi.json` with `appliances.read` to discover available installed services. Pin the returned contract fingerprint. Discovery never grants permission to invoke an operation.

This kit also includes a separate `BuildWithHQPlatformClient` and 129 Builder-session operations for app lifecycle and provisioning, backups and upgrades, domains and runtime control, account/team/API-client lifecycle, diagnostics and support, BuildSpec workflows, billing/storage, marketplace and templates. Their standalone [Platform Account OpenAPI](https://api.buildwithhq.com/v1/platform/openapi)  is packaged as `openapi/platform-owner.json`. The client calls `getBuilderSession` for each request; provide the current verified Builder login token through that callback. Tenant-organization billing retains tenant, user, DataRole and location checks; a tenant API credential does not grant Builder account authority. [Read the Builder Platform API guide](builder-platform-api.html).

Read billing availability at `GET /v1/platform/billing/catalog`, account resources at `GET /v1/platform/billing/resources`, and purchased entitlements at `GET /v1/platform/marketplace/entitlements`. SQL rechecks account ownership and action permissions. Catalog administration requires its existing operator permission. Public routes do not enable unconfigured payment providers, installation workers or deferred features. Check readiness and never blindly retry a purchase after a transport failure.

Verified server identity is passed to the secured stored procedures that authorize and perform the work. Frontends display their generated JSON. IDs supplied by a client select targets; they do not prove ownership.

## SDK package correction

The public SDK entry point includes only the clients distributed in this archive. Its relative imports are checked after packaging. Replace the complete SDK folder together when upgrading.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/current-api-contracts.html).

---
title: "Builder Platform API"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/builder-platform-api.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Builder Platform API

Use the 129-operation owner API for app, account, operations, diagnostics and BuildSpec workflows.

## In brief

- **Kit:** 1.20.70
- **Operations:** 129
- **Base path:** /v1/platform
- **Authentication:** Verified Builder session

[Download Developer Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Platform OpenAPI](https://api.buildwithhq.com/v1/platform/openapi) [Current contract changes](current-api-contracts.html)

## Choose the Builder contract

Use `BuildWithHQPlatformClient` when your trusted Builder integration manages apps and organizations owned by the signed-in Builder account. It is separate from the app-scoped `BuildWithHQConnector`. App credentials and tenant-user sessions cannot become Builder authority. The client asks `getBuilderSession` for the current session on every request so normal refresh, MFA, revocation and logout rules remain in force.

```
import { BuildWithHQPlatformClient } from "./sdk/index.js";

const platform = new BuildWithHQPlatformClient({
  baseUrl: "https://api.buildwithhq.com",
  getBuilderSession: async () => currentBuilderSession
});
```

Keep the session on a trusted server or in the supported Builder client boundary. Never place it in public source, page JSON, logs, prompts or a downloadable configuration file.

The Platform OpenAPI document is intentionally readable without a Builder session so tooling can discover its route and schema shape. This read grants no account access: all 129 operations still require verified Builder identity, ownership and action permission. The current kit gives each operation a typed success response and summary. Pin the SHA-256 in `sdk/platform-operation-coverage.json` to the packaged `openapi/platform-owner.json` before generating or updating a client.

## Choose the namespace by authority and resource

| Namespace | Use it for | Identity |
| --- | --- | --- |
| `/v1/platform/...` | The Builder account and its owned apps: provisioning, operations, team, diagnostics, BuildSpec, billing, marketplace and templates. | Current verified Builder session through `BuildWithHQPlatformClient`. |
| `/v1/apps/{saasAppId}/accounts/...` | Customer-organization and tenant-user provisioning by the SaaS application's trusted backend. | App-bound server credential with the exact tenant-management scope. |
| `/v1/apps/{saasAppId}/modules/...` | Typed first-class business modules such as Contacts, Work Orders, Reservations, Payments and Universal Inbox. | App credential or delegated tenant user; server applies tenant, DataRole, location and record scope. |
| `/v1/apps/{saasAppId}/objects/...` | Generic schema and record workflows for dynamic business objects that do not have a dedicated module method. | App or delegated-user credential with object/record permissions. |
| `/v1/apps/{saasAppId}/services/...` | Discover and invoke exact-version marketplace services running in their own VM or microVM and private data store. | Tenant context plus installed endpoint permission; discovery does not grant invocation. |
| `/v1/apps/{saasAppId}/ai/...` | Shared AI status, authorized record ingestion, rebuilds and multimodal search. | AI scopes plus the same tenant, DataRole, location and `CanAiReadRecords` envelope. |
| `/v1/apps/{saasAppId}/organization/...` | Singleton administration for the caller's current organization, including Snowflake export. | Active organization owner or an explicitly bound supported Builder context. |
| `/v1/apps/{saasAppId}/mcp` | The MCP transport over the same permission-filtered Developer API and installed-service catalog. | App credential or delegated tenant user with `mcp.use` and each tool's ordinary scope. |

Public assets, browser challenges, outside-form submissions and provider callbacks use their route-specific ingress protocol. Their lack of a normal bearer on the first request does not turn them into general anonymous API namespaces.

## Create an app safely after a timeout

`POST /v1/platform/apps` requires an `idempotencyKey` UUID in the JSON body with `appName` and `deploymentType`. Generate one key for one intended app and retain it until the result is known. If the response is lost, resend the same key and details: the server returns the original app and does not enqueue a second provisioning job. A different payload with that key returns HTTP 409. Use a new key for a separate app. The response `correlationId` helps support trace a request; it is not the retry key.

## Supported workflow groups

| Workflow | What is included | Kit guide and tests |
| --- | --- | --- |
| Apps and provisioning | Create an app, read provisioning progress and administrative detail, and use the supported suspend/resume lifecycle. | `PLATFORM-APP-LIFECYCLE.md`
`examples/platform-app-lifecycle.test.mjs` |
| Backups, upgrades, domains and runtime | Manage protected backup destinations, queue and inspect backups, request reviewed database upgrades, manage domains, and read/restart owned runtime state. | `PLATFORM-BACKUP-DOMAIN-RUNTIME.md`
`examples/platform-operations.test.mjs` |
| Identity, team and API clients | Integrate the existing Builder login/session protocol, manage account settings, team membership and invitations, and issue or revoke one-time API-client credentials. | `PLATFORM-IDENTITY-TEAM-API-CLIENTS.md`
`examples/platform-identity-team-clients.test.mjs` |
| Diagnostics and support | Read bounded app observability, search account audit, triage SaaS-developer problems, and inspect owned seller versions. Debug sessions for your app's pages use the Developer API design routes with a builder key, not this platform API. | `PLATFORM-DIAGNOSTICS-SUPPORT.md`
`examples/platform-diagnostics-support.test.mjs` |
| BuildSpec | Start and read a session, record requirements, validate, read progress, decide an exact pending review, and create an unpublished reuse candidate from completed work. | `PLATFORM-BUILDSPEC-WORKFLOW.md`
`examples/platform-buildspec-workflow.test.mjs` |

## Authority and state rules

The server derives the Builder user and account from the verified session. App and organization IDs select a target; they do not prove ownership. Each operation rechecks the owned app, active organization and required action permission through typed services and reviewed database contracts. Organization-owned payments remain on the app-scoped API because they require tenant, user, DataRole, location and payable-record authority.

Preserve returned row versions, revisions, review fingerprints, job IDs and idempotency fields. Refresh after a conflict. Do not blindly retry purchases, credential issuance, runtime restarts, backup starts or other consequential mutations after an ambiguous transport failure. Safe errors include a stable code and correlation ID; send support the correlation ID without credentials or customer payloads.

## BuildSpec approval remains mandatory

Validation and progress reads do not approve work. When progress reports a pending review, keep the job parked, display the reviewed summary and submit the exact review ID and fingerprint through the decision operation. A repeated identical decision is idempotent; a conflicting decision returns a conflict. Reuse candidates are created unpublished. The deterministic workflow contract does not promise that an external AI provider is configured or ready.

## What remains outside this client

Builder login, MFA, recovery, invitation acceptance, refresh and logout remain their existing identity protocol. Provider callbacks retain provider-signature validation. Health and discovery endpoints remain operational metadata. Global AI control, master-operator projections and explicit `/api/operator/...` history remain operator-only. Native tenant-session routes keep tenant role, DataRole, location and record visibility checks instead of accepting a Builder-session proxy.

The kit includes `docs/api-route-inventory-first-class-and-build-this.md` and the complete `skills/` source tree for route discovery and Skill authoring. Those files describe available contracts; they do not grant scopes, tools, records, GoClaw assignment or mutation authority.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/builder-platform-api.html).

---
title: "Connect organization logs to Snowflake"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/tenant-snowflake.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Connect organization logs to Snowflake

Set up, verify, operate and troubleshoot organization log export with Snowpipe Streaming.

## In brief

- **Owner:** Tenant organization
- **Delivery:** Eight Snowpipe pipes
- **Current operation:** Manual or hosted schedule
- **Authentication:** Server-generated key pair

BuildWithHQ can copy selected log metadata from your organization to a Snowflake account you control. Your app continues to use its own database; Snowflake is an analytics destination. The setup uses eight high-performance Snowpipe Streaming pipes, a dedicated service user and role, and a private key generated and encrypted on the BuildWithHQ server.

[Download Snowflake setup toolkit](../downloads/BuildWithHQ-Snowflake-Setup-Toolkit-1.0.1.zip) [Download Developer API Kit](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip) [Toolkit SHA-256](../downloads/BuildWithHQ-Snowflake-Setup-Toolkit-1.0.1.zip.sha256)

## Who manages the connection?

Each tenant organization has its own Snowflake destination. Its active owner manages it in **Admin → Snowflake**. Builders intentionally have support authority: a Builder-managed live API credential can manage the connection when it has explicit Snowflake scopes and is bound to that organization's active owner. A delegated tenant-user credential may use the same routes. Ordinary organization members cannot administer the connection.

The server derives app, organization and user identity from the verified session or credential, then checks current ownership through secured stored procedures. An organization ID in a request body does not grant access. Builder support must select the correct organization principal before calling these routes.

## What the Snowflake administrator needs

1. A Snowflake account and permission to create a dedicated service user, role, database, schema and streaming pipes.
2. The preferred `organization-account` identifier, without a URL. This release supports public Snowflake endpoints.
3. A database, schema, dedicated role and dedicated service-user name. Use simple unquoted identifiers.

Save the destination to generate its key pair on the server. Copy the returned setup SQL into a Snowflake worksheet for an administrator to review and run. The script creates eight tables and pipes and grants USAGE on the database/schema, INSERT on the tables and OPERATE on the pipes. It creates a new SERVICE user and does not replace an existing user. Choose names that are owned by your organization; do not run the script against an unrelated database. No ingestion warehouse or staging bucket is required; your analytics queries use your own query role and warehouse. Snowflake charges apply separately.

Only the public key reaches the browser or API response. Private keys are encrypted on the server. Do not paste private keys, passwords or tokens into configuration fields. For key replacement, save with `generateKey: true`, run the returned `keyRotationSql`, and test again.

## Step-by-step setup in the tenant app

1. Sign in as an active organization owner and open **Admin → Snowflake**. If the page says server setup is required, ask your BuildWithHQ operator to install the shared key-protection secret before you continue.
2. In Snowflake Account Details, copy the `organization-account` identifier, such as `exampleco-analytics`. Enter only that identifier in BuildWithHQ, without `https://`, a region suffix, or a browser fragment. Choose a dedicated database, schema, role and service-user name; the form proposes `BWHQ_LOGS`, `ANALYTICS`, `BWHQ_LOG_WRITER` and `BWHQ_LOG_SERVICE`.
3. Select **Save and generate connection key**. The destination remains paused. Save the public-key setup SQL locally and have your Snowflake administrator review its database, schema, object names and grants. The downloadable offline checker can confirm that all eight expected tables and pipes are present; it does not execute SQL or authenticate to Snowflake.
4. Run the reviewed SQL in the intended Snowflake account. If a service user with the chosen name already exists, stop and select a new dedicated name or review a controlled migration. Do not grant broad account privileges just to make the connection test pass.
5. Back in BuildWithHQ, select **Test connection**. Look for **Connection test passed**; a green HTTP response alone is not proof. The test authenticates and opens a separate empty test channel on each of the eight pipes.
6. Select **Enable export** and confirm. You can select **Export next batch** for a manual run; repeat until caught up. For automatic export, confirm that the page reports the scheduled host is available, select a cadence under **Automatic export**, then select **Enable schedule** and confirm. The destination must remain verified and enabled. Each completed run shows a safe result and correlation reference in recent history.

## What is exported?

| Dataset | Snowflake table | Examples of included metadata |
| --- | --- | --- |
| AI query events | `BWHQ_AI_QUERY_EVENTS` | Model name, token counts, duration, outcome and integrity hashes |
| Login events | `BWHQ_LOGIN_EVENTS` | Login outcome, user/reference identifiers and time |
| Page view events | `BWHQ_PAGE_VIEW_EVENTS` | Route/view identifiers, duration and URL hash |
| Record change events | `BWHQ_RECORD_CHANGE_EVENTS` | Record/module identifiers, change type and time |
| Field access events | `BWHQ_FIELD_ACCESS_EVENTS` | Field key, access type and outcome |
| Field change events | `BWHQ_FIELD_CHANGE_EVENTS` | Field/record identifiers and actor reference |
| File access events | `BWHQ_FILE_ACCESS_EVENTS` | File/record identifiers, access type and outcome |
| Automation job events | `BWHQ_AUTOMATION_JOB_EVENTS` | Job type, status, attempt and duration |

Each table stores a source app ID, organization ID, source event ID, a structured `RECORD` value and export time. The export manifest explicitly excludes passwords, session tokens, prompt/response text, raw URL, email, IP address, record/file contents, raw diagnostic payloads and error-message text. Snowflake retention and access policy are your responsibility after delivery.

## Verify delivery and recover a retry

In **Recent export history**, check each dataset result, batch row count and correlation reference. An empty dataset can complete with zero rows; that does not indicate a failed pipe. A real approved account passed all eight test channels and hosted append checks. A forced local checkpoint failure after Snowflake committed a row left the checkpoint unchanged; the next run recovered the remote offset and completed without duplicating that row. Temporary test rows were removed. This is integration evidence, not a guarantee that every future batch will succeed.

The toolkit includes `verify_counts.sql` for an authorized read role. Its eight row counts provide a simple destination check; a service user with only streaming permissions need not have SELECT. For exact progress, compare the channel's `last_committed_offset_token` with BuildWithHQ's source checkpoint. A request acknowledgement is not the commit fence. If a request times out, refresh the page and retry: the stable channel is reopened, its committed offset is read, and only the uncommitted suffix is sent. Do not reset, drop or recreate a pipe/channel while a checkpoint exists without a reviewed recovery plan.

## Pause, rotate, or troubleshoot

**Pause schedule** stops future automatic runs while leaving manual export available. **Pause export** stops new batches entirely; both preserve confirmed checkpoints, completed history and data already in Snowflake. A run already in progress finishes under its lease before pause takes effect. To rotate the key, use **Replace the connection key**, run the returned public-key update command on the same dedicated service user, then test again before enabling. Protect the BuildWithHQ server's encryption master key separately from the Logs database; losing that key requires a new connection key.

| Result | What to check |
| --- | --- |
| `authentication_failed` | Account identifier, dedicated service-user name and its registered public key |
| `permission_denied` | Default role, USAGE on database/schema, INSERT on tables, OPERATE on pipes |
| `pipe_not_found` | Chosen database/schema and all eight pipe names in the setup script |
| `configuration_or_rows_invalid` or `rows_rejected` | Pipe definitions, destination tables and Snowflake channel row errors |
| `timeout`, `commit_timeout` or `rate_limited` | Snowflake availability and network egress; refresh and retry without resetting the channel |
| `remote_offset_regressed` | Stop. The remote channel is behind the local checkpoint; ask an operator to plan replay or restore. |
| `credential_unavailable` | BuildWithHQ's protected key-storage installation and service access |

Give support the correlation reference, dataset and safe result code. Do not send passwords, private keys, JWTs, scoped tokens, browser cookies or entire raw log rows. If an HTTP request succeeds but `destination.lastResult` is not `connected` or `export_completed`, treat the operation as failed.

## Public routes and scopes

All routes start with `/v1/apps/{saasAppId}/organization/snowflake`. The app path is checked against the credential; the organization comes from its verified principal.

| Method and suffix | Scope | Action |
| --- | --- | --- |
| GET | modules.snowflake.read | Settings, public key, setup SQL, verification, checkpoints and recent history |
| PUT | modules.snowflake.write | Create/update settings or replace the key |
| POST /test | modules.snowflake.write | Check authentication and all eight pipes using separate test channels |
| PUT /enabled | modules.snowflake.write | Enable or pause export |
| POST /export | modules.snowflake.write | Export the next bounded batch |
| PUT /schedule | modules.snowflake.write | Enable, change cadence or pause automatic export |

Save accepts `accountIdentifier`, `databaseName`, `schemaName`, `roleName`, `principalName`, `generateKey` and, for updates, `expectedRowVersion`. Creating a destination requires key generation. Other mutations require the latest returned `expectedRowVersion`; enable/pause also requires an explicit boolean `isEnabled`. Read again after HTTP 409. Unknown body fields are rejected.

The generated `BuildWithHQModuleClient` exposes `snowflakeGet`, `snowflakeSave`, `snowflakeTest`, `snowflakeSetEnabled`, `snowflakeSetSchedule` and `snowflakeExport`. Pass mutation payloads under `body`. Scheduling takes `isEnabled`, `cadenceMinutes` (5–1440) and the current `schedule.rowVersion` when updating an existing schedule. Read again after HTTP 409. `schedulingAvailable` reports whether a hosted worker has checked in recently; it does not say the schedule is enabled.

## Test, enable and export

A saved or rotated connection stays paused until its connection test succeeds. Saving settings invalidates earlier verification. Test/export responses contain safe `destination.lastResult` codes; HTTP 200 alone does not prove a provider test succeeded. Require `connected` after testing or `export_completed` after exporting. HTTP errors use a safe explanation, stable code and correlation ID.

Each export handles up to 100 entries per dataset. Run another batch to continue. Stable channels and committed offsets recover an interrupted batch before advancing local checkpoints. A busy operation, stale revision, rejected rows or regressed remote offset stops progress safely. The history displays the latest 25 completed dataset runs. Pausing preserves history and data already in Snowflake.

Included datasets cover AI usage, login outcomes, page views, record changes, field access/changes, file access and automation job metadata. Passwords, session tokens, prompts, responses, record/file contents and raw diagnostic payloads are excluded. Export does not extend local diagnostic retention or create staged log files.

## Current availability and cost

Manual and hosted scheduled export have been exercised against a real approved Snowflake account through a route-owned disposable tenant. Scheduling is available only while a configured worker has checked in recently; if the worker stops, the API reports `schedulingAvailable: false` and new enable requests are rejected. A schedule does not start when you merely enable the destination. The hosted worker sends at most 100 rows per dataset each cycle, checks the route and lease, and retries from Snowflake's confirmed offset. Private connectivity, managed encryption-master-key rotation and destination moves after checkpoints require a separate operator review.

Snowflake bills ingestion/storage and any queries under its own account terms. BuildWithHQ does not set or control Snowflake prices; review your Snowflake usage and credit limits in that account. A query warehouse is needed when you run analytics queries, even though the ingestion path itself does not require a dedicated warehouse.

## Downloads and Developer API Kit

The [Snowflake setup toolkit](../downloads/BuildWithHQ-Snowflake-Setup-Toolkit-1.0.1.zip)  includes this workflow as a README, an offline `check_setup.py` script and read-only `verify_counts.sql`. It contains no credentials and never contacts Snowflake. The same files are under `snowflake/` in [Developer API Kit 1.20.70](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.70.zip), alongside the generated OpenAPI contract and typed SDK. Verify the adjacent SHA-256 files before distributing either ZIP.

If protected server key storage is unavailable, ask the operator to install the shared encryption key on the serving API instances. The operator must back it up separately from the Logs database; losing it requires replacing tenant connection keys.

References: [account identifiers](https://docs.snowflake.com/en/user-guide/admin-account-identifier), [key-pair authentication](https://docs.snowflake.com/en/user-guide/key-pair-auth), [Streaming REST tutorial](https://docs.snowflake.com/en/user-guide/snowpipe-streaming/snowpipe-streaming-high-performance-rest-tutorial), and [access control](https://docs.snowflake.com/en/user-guide/snowpipe-streaming/snowpipe-streaming-access-control).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/tenant-snowflake.html).

---

# Section: Errors & Troubleshooting

---
title: "Error code reference"
section: "Errors & Troubleshooting"
canonical_url: "https://support.buildwithhq.com/errors/error-codes.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Error code reference

Common error codes and families, safe next steps, and help with unlisted responses.

## In brief

- **Coverage:** Common codes and families
- **Filter:** Type a code or word below

This lookup covers common codes and code families. The filter matches codes, names, and descriptions; it is not an exhaustive list of every endpoint response.

| Code | Kind | What it means & what to do |
| --- | --- | --- |
| `internal_error` | Error | **Unexpected server error**
The native runtime returns this code with HTTP 500 when an unexpected failure prevents a normal response. Keep the correlation ID and safe message. Before repeating a write, reload the current records and review whether it already took effect; use Getting help if the outcome is unclear. |
| `empty_location_scope` | Error | **No active authorized locations**
An assigned location is inactive or no longer belongs to this organization. The user's location scope is denied until an organization admin assigns an active location or reviews the user's scope. CompanyIQ, OpsAtlas and Developer AI return HTTP 403 with a correlation ID; retrying without a scope change will not help. |
| `51005` | Error | **AI assistant daily action quota reached**
The user's assistant hit its per-day action budget. Further actions queue until the daily reset. Builders can review per-user quotas in assistant settings. |
| `51000–51999` | Error | **Request validation failed (builder console)**
The request was well-formed but not valid — a missing field, a bad value, or an operation the current state doesn't allow. The message names the specific problem. Returned as HTTP 400. |
| `55000–55099` | Blocked | **Account lifecycle state blocks the action**
The account's state — unverified email, trial expired, past due, suspended, or locked — prevents this action. Resolve the state in the console (verify email, update payment) and retry. Returned as HTTP 423. |
| `55100–55199` | Error | **Authentication or session failure**
Sign-in failed, the token is expired or revoked, or an MFA step is required. Refresh once; if that fails, sign in again. Returned as HTTP 401. |
| `57100–57599` | Error | **Marketplace operation refused**
A marketplace action failed a rule: missing store or payout permission, a product/offer not in the right state to activate, a price that doesn't match the billing model, or a payout exceeding the available balance. The message names the specific requirement — meet it and retry. |
| `E003–E007` | Error | **Page content structure invalid**
The page document violates a structural rule — an unknown block type, a malformed property, or content the renderer can't accept. The editor lists each finding with its block; fix the listed blocks to unblock saving. |
| `E021` | Blocked | **Block identity would be lost**
A raw JSON edit removes or duplicates a block's stable identity, which future template upgrades rely on to merge safely. Cancel and restore the identity, or acknowledge to proceed — acknowledged blocks are treated as brand-new content in all future upgrades. |
| `W104–W105` | Blocked | **Page content warning**
A draft may be saved with warnings, but the current tenant page publication gate requires zero errors and zero warnings. Review the validation report and resolve these findings before publishing. |
| `429 + retryAfterSeconds` | Blocked | **Rate limited**
Too many attempts in the window (for example, 10 sign-in failures in 15 minutes). Wait the number of seconds indicated, then retry. Hammering extends nothing. |

## Reading a code

Responses may use named or numeric codes. Page-content reports also use `E`-codes for errors and `W`-codes for warnings. Saving a draft and publishing are separate checks; the tenant page publication gate requires both errors and warnings to be resolved. Use the HTTP status and safe message from the actual response; a code alone may not identify the cause. When contacting support, include the exact code and correlation ID when present.

## When a code is not listed

Use [Getting help](getting-help.html)  with the exact code, safe message, HTTP status, and correlation ID when provided. If a write was not confirmed, reload and review the current records before submitting another write. Do not assume that a failed response means nothing changed.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/errors/error-codes.html).

---
title: "Can't sign in"
section: "Errors & Troubleshooting"
canonical_url: "https://support.buildwithhq.com/errors/sign-in-problems.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Can't sign in

Lockouts, expired links, unverified accounts, and MFA trouble.

## In brief

- **Audience:** Everyone
- **Most common cause:** Throttle lockout

## Locked out after failed attempts

Ten failed attempts in 15 minutes locks sign-in for 15 minutes. The lock releases on its own — waiting is the fix, and support cannot lift it early.

## Verification or reset link doesn't work

Links are one-time and expire. Request a fresh one and use the newest email; older links in your inbox are already dead.

## Lost your authenticator

Use one of the recovery codes you saved at enrollment — each works once. Out of codes? An account owner can help re-establish access.

## Account is suspended or past due

Sign-in can be blocked by account state, not credentials. Builders: check [payment issues](../billing/payment-issues.html). End users: contact your administrator.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/errors/sign-in-problems.html).

---
title: "Domain and certificate problems"
section: "Errors & Troubleshooting"
canonical_url: "https://support.buildwithhq.com/errors/domain-problems.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Domain and certificate problems

Verification stuck, certificate warnings, and wrong-site symptoms.

## In brief

- **Audience:** Builders
- **First check:** The DNS record, character for character

Nine domain problems out of ten are the DNS record: wrong host, wrong target, or an old conflicting record on the same name. Start there before anything else.

## Checklist

1. Compare the record at your DNS provider to what the console shows, character for character.
2. Delete any pre-existing A or CNAME record on the same hostname — conflicts silently win.
3. Allow for propagation: minutes usually, up to 48 hours worst case.
4. Re-run **Verify** in the console after fixing.

## Certificate warnings

Certificates issue automatically after verification passes. A browser warning during setup means propagation isn't done; a warning appearing on a previously working domain means the DNS record changed — check whether someone edited it.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/errors/domain-problems.html).

---
title: "Page won't save or publish"
section: "Errors & Troubleshooting"
canonical_url: "https://support.buildwithhq.com/errors/page-save-problems.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Page won't save or publish

Validation errors, edit locks, and the E021 identity gate.

## In brief

- **Audience:** Builders
- **Related:** Raw JSON mode

## “Someone else is editing”

Pages allow one editor at a time. The banner names who holds the lock. Locks renew while the holder works and expire shortly after they stop — if the named person has left for the day, take-over is offered once their lock lapses.

## Validation errors on save

The editor lists each problem with the block it belongs to. Fix the listed blocks; the save button unblocks when the list is empty. Codes in the `E0xx` range are content-structure problems, explained in the [error reference](error-codes.html).

## The E021 prompt in code view

`E021` means your raw edit removes or duplicates a block identity that future template upgrades depend on. Cancel and restore the identity if you want upgrades to keep working for those blocks; acknowledge only if you understand they'll be treated as new content from now on.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/errors/page-save-problems.html).

---
title: "Getting help"
section: "Errors & Troubleshooting"
canonical_url: "https://support.buildwithhq.com/errors/getting-help.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Getting help

What to check first, what to include when you write in, and where.

## In brief

- **Before writing in:** Search these docs + the error reference
- **Response:** See support policy

Start with the search box and [error code reference](error-codes.html). The reference covers common codes and families; if your response is not listed, use the details below.

## Reading public documentation from a script

The [public source index](../llms.txt), [combined documentation](../llms-full.txt), and raw Markdown links are public documentation. If a scripted download receives Cloudflare error `1010` while a browser can read the same URL, give the client an accurate application name and version in its `User-Agent`. Cloudflare documents this default-client behavior in its [error 1010 guide](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/error-1010/). Application API requests still require their normal credentials and permissions.

This Python example identifies the example client. Use your own application's name and version when integrating it:

```
from urllib.request import Request, urlopen

request = Request(
    "https://support.buildwithhq.com/llms.txt",
    headers={"User-Agent": "BuildWithHQDocsExample/1.0"},
)
with urlopen(request, timeout=15) as response:
    source_index = response.read().decode("utf-8")
print(source_index)
```

## If you still need us

Include these and you'll usually get a one-reply resolution:

- The **exact error code and message**, verbatim
- What you were doing, step by step, and what you expected
- The application and page involved, and roughly when it happened
- A screenshot if the problem is visual

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/errors/getting-help.html).

---

# Section: Billing & Account

---
title: "Plans and trials"
section: "Billing & Account"
canonical_url: "https://support.buildwithhq.com/billing/plans-and-trials.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Plans and trials

How trials end, what plans include, and how to change plans.

## In brief

- **Trial end:** Enforced automatically
- **Changes:** Self-service

New accounts begin on a trial with full access. Trial expiry is enforced by the platform on a schedule — when your trial ends, you'll be prompted to pick a plan before continuing.

## Choosing and changing plans

Plans differ by allowances — applications, storage, AI budget, team size. Upgrades apply immediately; downgrades apply at the next billing cycle so you never lose paid time.

## Where payment happens

Payments are processed by Stripe. Your card details are entered on and stored by Stripe — the platform never sees or stores your card number.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/billing/plans-and-trials.html).

---
title: "Invoices and receipts"
section: "Billing & Account"
canonical_url: "https://support.buildwithhq.com/billing/invoices-and-receipts.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Invoices and receipts

Find, download, and understand your invoices.

## In brief

- **Location:** Billing → Invoices
- **Format:** PDF

Every charge produces an invoice available in your billing history, downloadable as PDF.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/billing/invoices-and-receipts.html).

---
title: "When a payment fails"
section: "Billing & Account"
canonical_url: "https://support.buildwithhq.com/billing/payment-issues.html"
reviewed_at: "2026-09-14"
authority: Official
---

# When a payment fails

The grace period, what gets restricted, and how to restore service.

## In brief

- **Sequence:** Past due → grace period → suspended
- **Fix:** Update the card; retry is automatic

A failed renewal doesn't cut you off instantly. The account enters **past due** with a grace period: you'll see prompts, retries happen automatically, and service continues while you fix the payment method.

## If the grace period lapses

The account moves to **suspended**: builder console actions are restricted until payment succeeds. Updating your card triggers a retry; success restores the account immediately.

Important

Your customers' applications are the priority during dunning. Restrictions target the builder console first — document the exact end-state for tenant-facing apps in a prolonged suspension before launch.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/billing/payment-issues.html).

---
title: "Charging your customers"
section: "Billing & Account"
canonical_url: "https://support.buildwithhq.com/billing/revenue-share.html"
reviewed_at: "2026-10-20"
authority: Official
---

# Charging your customers

Preview reference: the connected-account billing model and its release prerequisites.

## In brief

- **Availability:** Release-gated preview
- **Rails model:** Stripe Connect
- **Commercial model:** Platform revenue share

Important

This connected-account billing reference is not confirmation of an available production workflow. Onboarding, checkout, accounting, refunds and payouts require their own release acceptance before use.

The reference model connects a Builder's Stripe account, product prices and an explicitly agreed platform revenue share through Stripe Connect. It does not establish that connecting an account or setting a price enables a complete billing journey. Stripe controls the connected account's processing and bank-payout timeline; BuildWithHQ does not promise a separate fixed arrival date.

Tenant business payments and refunds are separate capabilities with their own secured record, provider and accounting contracts. This connected-account reference does not make tenant refunds available or authorize financial tests or held background workers.

---

Capability review: 2026-10-20. [View the canonical guide](https://support.buildwithhq.com/billing/revenue-share.html).

---
title: "Cancel or close your account"
section: "Billing & Account"
canonical_url: "https://support.buildwithhq.com/billing/closing-your-account.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Cancel or close your account

What cancellation does, when it takes effect, and what happens to data.

## In brief

- **Effect:** End of current period
- **Data:** Export first

Cancelling stops future renewals; your plan runs to the end of the paid period. Before cancellation takes effect, the account owner can create and verify a current export of customer records, files, AI data, operational history, and audit history. Builders should also export the versioned JSON and JSON Schema definitions for their pages and workflows.

## Before closing the account

- Run the owner-only data export and verify the included checksums.
- Download the separate application-definition export for pages and workflows.
- Confirm that customer-owned S3 restore bundles are current, when configured.
- Record the credentials and external-service connections that must be recreated; secrets are deliberately not placed in exports.

The retention and deletion schedule after the paid period is the schedule stated in the customer's applicable service terms or enterprise agreement. Do not rely on a post-cancellation recovery window as a substitute for a verified backup.

Note

Exports can be used to build an independent replacement system. If BuildWithHQ ceases operation, the continuity plan also provides the managed API code and JSON interpreter needed to run exported application definitions in a cloud environment or virtual machine. Read [Business continuity and application portability](../trust/business-continuity-and-portability.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/billing/closing-your-account.html).

---

# Section: Partners & MSPs

---
title: "Partner program overview"
section: "Partners & MSPs"
canonical_url: "https://support.buildwithhq.com/partners/program-overview.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Partner program overview

How MSP partnership works: attribution, earnings, and what you operate.

## In brief

- **Status:** Early access — details may change
- **Model:** Lifetime attribution

Note

The partner program is in early access. This section describes the working model; confirmed terms arrive with your partner agreement.

MSP partners bring builders to the platform and share in the revenue for as long as those builders remain under the partner's management. Builders pay the platform directly; partner earnings are calculated and paid out by the platform — there's no invoicing between you and your builders to run.

## What partners can operate

Partners can host AI processing for their builders on their own hardware, keeping inference local while the platform manages software delivery to it. Partners may also earn commissions on template marketplace sales.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/partners/program-overview.html).

---
title: "Deploying the partner appliance"
section: "Partners & MSPs"
canonical_url: "https://support.buildwithhq.com/partners/appliance-deployment.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Deploying the partner appliance

Run the AI appliance on your own hardware: enrollment, connectivity, and requirements.

## In brief

- **You provide:** The hardware
- **Platform provides:** Software, updates, fleet connectivity

The partner appliance is an early-access deployment model for AI inference on hardware you own and operate. Enrollment and private management connectivity are planned; self-service deployment has not been validated for general use. Arrange a reviewed operator-assisted deployment before relying on this path.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/partners/appliance-deployment.html).

---
title: "Deploy the SaaS asset domain and storage root"
section: "Partners & MSPs"
canonical_url: "https://support.buildwithhq.com/partners/asset-domain-and-storage-deployment.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Deploy the SaaS asset domain and storage root

Configure persistent asset storage and route assets.buildwithhq.com to the tenant runtime without exposing database or filesystem authority.

## In brief

- **Public host:** assets.buildwithhq.com
- **Storage:** Operator selected
- **Proxy rule:** Preserve Host
- **Docker:** Not required

The tenant runtime stores SaaS files beneath one operator-controlled root and serves explicitly public design assets through `assets.buildwithhq.com`. Builders may choose virtual folders inside their SaaS, but only an appliance operator can select or change the physical storage location.

## 1. Choose persistent storage

1. Create a dedicated persistent directory on the appliance volume. Do not use a temporary deployment, build-output, user-profile, or source-tree directory.
2. Grant the tenant-runtime operating-system identity read, create, and delete access only to that directory.
3. Set `BWHQ_FILE_STORAGE_ROOT` for the tenant-runtime process before it starts.
4. Include the directory in the appliance backup, restore, capacity, and integrity-monitoring plan.

| Host | Example value |
| --- | --- |
| Linux appliance guest | `/var/lib/buildwithhq/files` |
| Windows service host | `D:\BuildWithHQData\Files` |

Important

Changing BWHQ_FILE_STORAGE_ROOT does not move existing bytes. Stop uploads, copy and verify the complete existing tree while preserving relative keys, change the setting, then verify old private and public assets before reopening writes.

## 2. Configure the asset host

Set the ASP.NET Core configuration key `Assets:PublicHost`, normally through environment variable `Assets__PublicHost=assets.buildwithhq.com`. The public controller returns 404 on a different Host value, so the reverse proxy must preserve the original request host.

1. Create DNS for `assets.buildwithhq.com` pointing at the approved public edge or load balancer.
2. Issue and renew a valid TLS certificate for that exact hostname.
3. Route HTTPS requests for that host to the tenant-runtime service.
4. Preserve `Host: assets.buildwithhq.com`; do not rewrite it to the internal service name.
5. Do not expose SQL Server, storage paths, management endpoints, or a directory-listing handler on the asset virtual host.

Note

The application generates public URLs with the fixed production origin https://assets.buildwithhq.com. Assets__PublicHost is a request-host validation setting, not a second public URL generator.

## 3. Understand the route and database boundary

A request has only `/{saasAppId}/{assetId}`. The server resolves an active SaaS identity through the Customers control-plane contract, creates a server-owned routed tenant connection, and retrieves metadata only when the asset is explicitly public and active. Storage provider and relative storage key stay inside the service.

API users and browsers receive no SQL credential, table permission, filesystem permission, server path, or database name. Runtime SQL principals retain allow-listed stored-procedure execution only; they do not receive DDL authority.

## 4. Browser delivery policy

- Validated CSS and reviewed passive image, video, font, and PDF MIME types may render inline.
- Other accepted files are returned as `application/octet-stream` attachments with `X-Content-Type-Options: nosniff` and a sandbox content-security policy.
- Public responses allow cross-origin asset use and use a one-year immutable cache because the URL is identity-versioned.
- DLL, COM, and EXE extensions are rejected before storage. Filename normalization also blocks case and trailing-dot variants.

## 5. Verify the deployment

1. Start the tenant runtime with both settings present.
2. In a disposable SaaS, upload a small public PNG in App Assets and copy its returned URL.
3. Request the URL from outside the appliance network and confirm HTTP 200, TLS trust, `Access-Control-Allow-Origin: *`, `X-Content-Type-Options: nosniff`, and immutable cache control.
4. Upload a private asset and confirm its authenticated `/api/assets/.../content` route works while no public asset-domain URL is issued.
5. Remove the disposable public asset and confirm the old URL returns 404.
6. Request the same path using the wrong Host header and confirm it returns 404.

Important

Do not call the deployment complete from a loopback-only test. DNS, certificate trust, preserved Host routing, public reachability, and a route-resolved disposable SaaS must all be exercised.

## 6. Operations checklist

- Monitor storage capacity, write failures, public 404/5xx rates, and certificate expiry.
- Back up asset bytes with the corresponding tenant databases and retain restore evidence.
- Keep directory browsing disabled and storage inaccessible from the public web server except through the asset controller.
- Use a controlled migration procedure before changing the root.
- Remember that current template installation does not yet copy/remap asset bytes into a destination SaaS.

Builders should continue with [Host SaaS CSS, logos, images, and design assets](../builder-guide/saas-css-and-design-assets.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/partners/asset-domain-and-storage-deployment.html).

---
title: "How appliance updates work"
section: "Partners & MSPs"
canonical_url: "https://support.buildwithhq.com/partners/appliance-updates.html"
reviewed_at: "2026-09-14"
authority: Official
---

# How appliance updates work

The planned signed-update model and its current availability.

## In brief

- **Delivery:** Pulled, signed, versioned
- **Switchover:** Only after health checks pass

Note

Automatic appliance updates are a planned early-access capability. No generally available fleet update service or operator recovery path has been validated yet; do not assume an appliance will update itself.

The intended update design uses signed, versioned bundles installed alongside the running version. Health checks would gate switchover and keep the previous version available when a candidate fails. This is a design description, not an instruction to enable unattended updates today.

## For an operator-assisted deployment

- Agree on a reviewed update and rollback plan with the BuildWithHQ operator before changing the appliance.
- Verify the signed bundle, health checks, and rollback result for that specific deployment.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/partners/appliance-updates.html).

---

# Section: Trust & Security

---
title: "Security architecture"
section: "Trust & Security"
canonical_url: "https://support.buildwithhq.com/trust/security-architecture.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Security architecture

The structural guarantees: isolation, a single enforcement point, and identity that can't be spoofed.

## In brief

- **Design principle:** Security is structural, not procedural
- **Audience:** Evaluators, security reviewers

The platform's security posture rests on a small number of structural decisions — properties of how the system is built, not policies someone must remember to apply.

## Isolation by construction

Every application gets physically separate databases for live data, audit history, and AI. Tenant data within an application is partitioned by the permission model on every read. There is no shared table where a filter mistake could leak one customer's data to another's application.

## One enforcement point

Tenant record access uses the shared account, DataRole, Location, and record-permission model. Each route must also verify its credential, scope, and action permissions. New features must use these controls and pass isolation tests; a shared security model does not remove the need to test each integration.

## Identity is server-derived

The server establishes the calling principal from a verified session or API credential. Requests can include app, account, user, and record IDs as targets, but those IDs are not authorization proof. The server checks that every target belongs within the caller's permitted scope.

## Presentation can't grant access

Page layouts and AI features consume data *after* permission filtering. Changing what a page shows, or what an assistant is asked, can narrow what appears — never widen it.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/trust/security-architecture.html).

---
title: "Tenant Data Security"
section: "Trust & Security"
canonical_url: "https://support.buildwithhq.com/trust/tenant-data-security.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Tenant Data Security

How User Types, DataRoles, and Locations work together to shape an app experience and protect tenant data.

## In brief

- **User Types:** Menus and page experience
- **DataRoles:** Data and action permissions
- **Locations:** Where records and people are scoped

BuildWithHQ separates three questions that are often mixed together: **what experience should this person see, what may they do with data, and which locations are in scope?** User Types, DataRoles, and Locations answer those questions independently and are evaluated together for each signed-in user.

[User Types](user-types.html) [DataRoles](data-roles.html) [Locations](locations.html) [Menu editor guide](../builder-guide/menus-user-types.html)

## Three controls, three different jobs

| Control | Question it answers | Typical examples |
| --- | --- | --- |
| **User Type** | Which menu, home/dashboard, and SaaS app pages should this kind of person be shown? | Owner, staff member, customer, field technician |
| **DataRole** | Which data may this person read, add, edit, delete, export, or use with AI, and which named actions may they perform? | Sales reader, support editor, billing approver |
| **Location** | Which assigned places are in this person's record scope? | All Locations, Las Vegas office, Reno office, or Las Vegas + Reno |

## How they work together

Think of access as an intersection. The User Type shapes the visible app experience. DataRoles supply data and action grants. Locations narrow location-assigned records. Record-specific, field, secure-field, workflow, approval, and AI rules may narrow the result further.

For example, a user may have the *Support Staff* User Type, both *Cases Reader* and *Case Editor* DataRoles, and membership in the Las Vegas and Reno locations. Their menu can show support pages; their combined active roles can allow permitted case reads and edits; and location filtering limits location-assigned records to Las Vegas and Reno. None of those settings grants access outside the current SaaS app and tenant account.

## The server resolves the final envelope

1. The authenticated session establishes the SaaS app, tenant account, and active user.
2. The user's User Type selects the intended menu, portal/dashboard, and page experience.
3. All active DataRole memberships and granular permission keys are resolved.
4. The user's All Locations, single-location, or multi-location scope is resolved.
5. The requested record, field, and action are checked again before data is returned or changed.

Note

The browser never proves its own tenant, role, location, or user identity. Those values come from the verified server session, and reviewed stored procedures apply the final data checks.

## Route eligibility and data authorization

User Types select menus, layouts, and starting pages. An active, entitled published page can be opened directly even when it is absent from the current menu. Each request uses the verified user, tenant organization, SaaS app, and persisted page identity; the database resolves the applicable tenant page, customization or fork, or base page.

Every page component, search, download, API call, AI retrieval, and mutation is authorized independently with Personal ownership, DataRoles, Locations, record, field, and action rules. Private records and All Locations settings are checked by the secured data contracts. A page or menu never supplies a guessed record scope.

Note

Assigning a page places it in the User Type experience. It does not grant the data or actions displayed by that page.

## A practical review checklist

- Give each person the User Type whose menu matches their job.
- Assign only the DataRoles needed for that job; remember that grants from multiple roles combine.
- Use All Locations only for people who genuinely need tenant-wide location access.
- Assign one or multiple named locations for regional or office-scoped users.
- Test direct access to entitled published pages both inside and outside each menu, verify unavailable pages are rejected, then test search, exports, AI, records, fields, and writes as representative users.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/trust/tenant-data-security.html).

---
title: "User Types: menus and SaaS pages"
section: "Trust & Security"
canonical_url: "https://support.buildwithhq.com/trust/user-types.html"
reviewed_at: "2026-09-14"
authority: Official
---

# User Types: menus and SaaS pages

User Types define the menu, landing experience, and SaaS app pages each kind of person is shown.

## In brief

- **Controls:** Navigation and page experience
- **Per person:** One current User Type
- **Does not control:** Data authorization

A **User Type** describes the kind of app participant a person is. It determines the navigation and SaaS page experience intended for that audience: which menu is loaded, which entries it contains, and which portal or dashboard is used as the starting point.

[Tenant Data Security](tenant-data-security.html) [DataRoles](data-roles.html) [Locations](locations.html) [Build menus by User Type](../builder-guide/menus-user-types.html)

## What a User Type defines

- **Menu:** the ordered navigation items shown to that type of user.
- **SaaS pages:** the pages linked into that audience's app experience.
- **Starting experience:** the portal and dashboard/home page associated with the type.
- **Audience shape:** a stable key and friendly name that templates and menus can use.

Examples might include Owner, Office Staff, Field Technician, Customer, or Vendor. These are app-design choices, not universal built-in authorization levels.

## One person, one current User Type

Each tenant user has one current User Type. Many people can share the same type, and each type can have its own menu. A page may appear in more than one type's menu, appear in different positions, or be absent from a type entirely.

## Menus choose navigation; pages can be reused

User Types define the navigation and starting experience. An active, entitled published page can be opened directly even when it is absent from the current menu. Different User Types can reuse the same persisted page and show different menu labels for it; changing the label does not create or select a different page.

The menu does not decide which records or fields the person may read or change. DataRoles, Locations, record and field rules, and action-specific permissions remain responsible for authorization on every eligible page.

Note

A page can be assigned to several User Types without duplicating it. Each signed-in person still receives only the data allowed by their own permission envelope.

## Designing User Types

1. List the distinct audiences that use the app.
2. Give each audience the smallest useful menu and a clear starting page.
3. Reuse pages across types when the workflow is shared; do not duplicate a page merely to change data access.
4. Assign DataRoles and Locations separately for each person's actual responsibilities.
5. Test assigned and unassigned direct-page behavior as a real user of each type, then test the data and actions on each eligible page.

Tip

Name User Types for the experience they receive, such as Customer Portal or Field Technician. Name DataRoles for the permission they grant, such as Cases Reader or Work Orders Editor.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/trust/user-types.html).

---
title: "DataRoles: data and action permissions"
section: "Trust & Security"
canonical_url: "https://support.buildwithhq.com/trust/data-roles.html"
reviewed_at: "2026-09-14"
authority: Official
---

# DataRoles: data and action permissions

DataRoles define what tenant data a person can see, add to, change, delete, export, or use through approved AI paths.

## In brief

- **Controls:** Data and action permissions
- **Per person:** One or multiple DataRoles
- **Combination:** Active grants accumulate

A **DataRole** is the data-permission part of tenant security. It defines what a person may see and what they may add to or change. A person can hold one DataRole or several, depending on their responsibilities.

[Tenant Data Security](tenant-data-security.html) [User Types](user-types.html) [Locations](locations.html)

## What DataRoles can grant

| Grant | What it means |
| --- | --- |
| Read | View permitted records and fields. |
| Create / add | Create new records through an authorized module or workflow. |
| Edit | Change permitted records and fields. |
| Delete | Use supported deletion operations where the record and workflow allow it. |
| Export | Export permitted records when export is enabled. |
| AI read | Allow eligible permitted records into secured AI retrieval; secure and AI-excluded fields remain excluded. |
| Named permission keys | Perform specific operations such as an approval or specialized module action. |

## Multiple DataRoles combine

Active role grants are cumulative in the current permission envelope. If one assigned role grants record reading and another grants editing, the user can receive both grants, still subject to every other check. Adding a role can therefore widen access; removing one can narrow it.

DataRoles do not erase Location scope. A user with edit permission for work orders and access only to the Las Vegas office may edit authorized Las Vegas work orders, not Reno work orders. Field security, record state, ownership, workflow locks, and action-specific rules may narrow an apparently broad role further.

## DataRole is not User Type

A User Type can show the Support menu while DataRoles decide whether that person is a read-only support observer, a case editor, or an approver. Two people can share the same User Type and see the same navigation while having different data access.

## Least-privilege examples

- **Cases Reader:** read permitted cases without create, edit, delete, or export.
- **Case Agent:** read, create, and edit permitted cases, but not approve refunds.
- **Billing Approver:** receive only the explicit billing/approval capabilities required by that job.
- **AI-enabled Analyst:** read permitted records and use AI retrieval, without gaining edit or export access.

Note

AI remains inside DataRole permissions. CanAiReadRecords can only enable AI use of records the person is otherwise permitted to read, and secure or AI-excluded fields stay out of model context.

## Reviewing a DataRole change

1. List the exact reads, additions, changes, exports, approvals, and AI operations the job requires.
2. Check every other role already assigned to the person because grants combine.
3. Confirm the intended Location memberships.
4. Test allowed and denied records, fields, searches, downloads, AI results, and mutations.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/trust/data-roles.html).

---
title: "Locations: where tenant data is assigned"
section: "Trust & Security"
canonical_url: "https://support.buildwithhq.com/trust/locations.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Locations: where tenant data is assigned

Locations define where records belong and whether a person works across all, one, or multiple tenant locations.

## In brief

- **Controls:** Location-assigned record scope
- **People:** All, one, or multiple locations
- **Records:** Named location or location-neutral

A **Location** describes where tenant data is assigned: an office, branch, property, region, service area, or other place meaningful to the business. Records can be assigned to a named Location, and people can work across All Locations, one Location, or multiple Locations.

[Tenant Data Security](tenant-data-security.html) [User Types](user-types.html) [DataRoles](data-roles.html)

## The three location states

| Person's scope | Assignment | Location records in scope |
| --- | --- | --- |
| **All Locations** | No named-location restriction | Las Vegas, Reno, future tenant locations, and location-neutral records, subject to DataRoles. |
| **One Location** | For example, Las Vegas office | Las Vegas and location-neutral records, subject to DataRoles. |
| **Multiple Locations** | For example, Las Vegas + Reno | Las Vegas, Reno, and location-neutral records, subject to DataRoles. |

In the current security contract, All Locations is the absence of named user-location restrictions, not a special wildcard Location record. One or more user-location assignments make the person location-scoped. Location-neutral records have no Location assigned and remain available across location scopes when the person's DataRoles allow them.

## Primary and additional Locations

A multi-location user can have one assignment marked primary. The primary Location can provide a sensible default for creation or filtering, while the full assignment set defines the named Locations in scope. Marking a Location primary does not by itself grant a broader DataRole.

## Location works with DataRoles

Location answers *where*; DataRole answers *what action*. A Las Vegas user still needs a DataRole that permits reading a customer record. An All Locations user with a read-only role still cannot edit it. Both dimensions must allow the requested operation.

## Assigning records

- Assign location-specific records, such as office work orders or regional customers, to the appropriate Location.
- Leave truly tenant-wide records location-neutral rather than inventing a fake global office.
- Only allow a user to create or move a record into a Location authorized for that user and operation.
- Apply the same scope to lists, detail pages, global search, relationships, files, exports, notifications, and AI retrieval.

Important

All Locations is powerful. Use it for tenant-wide responsibilities, not as a convenience when a person's actual offices have not yet been assigned.

## Example

Jordan belongs to Las Vegas and Reno, with Las Vegas marked primary. Jordan can work with records assigned to either office and with tenant-wide location-neutral records, but not records assigned only to Phoenix. What Jordan can do with the in-scope records still comes entirely from Jordan's active DataRoles and the record's other security rules.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/trust/locations.html).

---
title: "Encryption"
section: "Trust & Security"
canonical_url: "https://support.buildwithhq.com/trust/encryption.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Encryption

In transit, at rest, and per-field — including tenant-specific keys.

## In brief

- **Public HTTPS:** Cloudflare
- **Origin connection:** Deployment-specific
- **Field-level:** AES-256-GCM, per-tenant keys

Cloudflare handles public HTTPS for the hosted sites. The connection from Cloudflare to the origin server is a separate configuration: a browser padlock confirms public HTTPS, not origin encryption or mutual authentication.

The production deployment target includes verified origin TLS and authenticated origin pulls. These controls must be checked for each deployed surface before being represented as active. The Webhook Lab currently uses Cloudflare public HTTPS with an HTTP origin connection. Ask your deployment operator for the configuration and evidence applicable to your own environment.

## Field-level encryption

Fields marked secure are encrypted with AES-256-GCM using keys unique to each tenant. Decryption happens only at an explicit, authorized reveal. Encrypted values are structurally excluded from search indexes and AI processing — the exclusion is enforced by how values are stored, not by downstream filtering that could be forgotten.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/trust/encryption.html).

---
title: "TDS 8.0 and SQL Server 2025 transport security"
section: "Trust & Security"
canonical_url: "https://support.buildwithhq.com/trust/sql-server-2025-tds-security.html"
reviewed_at: "2026-09-14"
authority: Official
---

# TDS 8.0 and SQL Server 2025 transport security

How BuildWithHQ protects service-to-database traffic with SQL Server 2025, TDS 8.0, strict encryption, and layered authorization.

## In brief

- **Database path:** BuildWithHQ services only
- **Protection:** TDS 8.0 strict encryption
- **Customer setup:** None for managed hosting

BuildWithHQ uses Microsoft SQL Server 2025 for its database layer and the TDS 8.0 strict-encryption model for production service-to-database traffic. Customers do not connect their browser or app directly to SQL Server. BuildWithHQ APIs and workers establish the database sessions on their behalf, so the transport policy is applied centrally and cannot be weakened by an end-user setting.

## Where BuildWithHQ uses TDS

TDS carries traffic between authorized BuildWithHQ backend services and the appropriate database plane: the platform control plane, Template Library, Platform Orchestration, SaaS database, SaaS Vector DB, or SaaS Immutable Logs. Frontends receive bounded API responses; they never receive a SQL connection string, database credential, physical database name, or a way to select a database route.

## How the connection is protected

Production SQL connections require strict encryption and certificate validation. TDS 8.0 begins TLS before the traditional TDS pre-login exchange, keeping negotiation, authentication, commands, and results inside the encrypted session. BuildWithHQ uses the expected SQL Server hostname when validating the certificate and does not use `TrustServerCertificate` as a production bypass. A certificate that is expired, untrusted, or issued for the wrong name must cause the connection to fail closed.

SQL Server 2025 and TDS 8.0 support TLS 1.3 when the operating system and client driver support it, with TLS 1.2 as the compatible protocol floor for the strict TDS 8.0 path. BuildWithHQ pins supported drivers for services and workers rather than assuming that server settings can upgrade an incompatible client.

## Encryption is paired with least privilege

An encrypted connection is not automatically an authorized connection. Service database access uses a procedure-only role with direct table access denied. Each procedure must check the caller’s authority; membership in the service role does not grant record access. Browsers cannot issue SQL, controllers do not perform ad-hoc data changes, and tenant, SaaS app, user, DataRole and location scope are verified on the server. Routed database planes and organization-level authorization work together to enforce isolation.

## How BuildWithHQ validates the control

- Release checks lock database identities, procedure signatures, driver expectations, and object-level grants to the current database exports.
- Deployment validation checks the production certificate chain, validity period, intended hostname, and strict connection behavior.
- Health monitoring verifies that required database dependencies remain reachable without returning connection strings, credentials, or tenant data.
- Operational paths such as workers, jobs, recovery tooling, and replicas must use the same encrypted posture; an application-only check is not treated as complete coverage.

## What customers can verify

Managed-hosting customers do not need SQL access to test this control. Security reviewers can request BuildWithHQ’s current transport configuration statement and redacted release or deployment evidence. Appliance operators receive the corresponding server-certificate and strict-encryption deployment requirements because they control the SQL Server host; ordinary users still do not handle database credentials.

## What TDS does not replace

TDS protects data while it moves between BuildWithHQ services and SQL Server. It does not decide which records a person can read and does not protect database or backup files at rest. BuildWithHQ therefore combines TDS transport protection with server-derived authorization, DataRoles, location scope, reviewed stored procedures, field controls, audit evidence, and database/backup protection.

## Microsoft references

- [TDS 8.0 in SQL Server](https://learn.microsoft.com/en-us/sql/relational-databases/security/networking/tds-8?view=sql-server-ver17)
- [Connect using strict encryption](https://learn.microsoft.com/en-us/sql/relational-databases/security/networking/connect-with-strict-encryption?view=sql-server-ver17)
- [TLS 1.3 support](https://learn.microsoft.com/en-us/sql/relational-databases/security/networking/tls-1-3?view=sql-server-ver17)
- [SQL Server security best practices](https://learn.microsoft.com/en-us/sql/relational-databases/security/sql-server-security-best-practices?view=sql-server-ver17)

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/trust/sql-server-2025-tds-security.html).

---
title: "Audit trail and data disclosure"
section: "Trust & Security"
canonical_url: "https://support.buildwithhq.com/trust/audit-and-disclosure.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Audit trail and data disclosure

The immutable history of what happened, and the verifiable ledger of third-party access.

## In brief

- **Audit history:** Append-only, separate database
- **Third-party access:** Tamper-evident ledger

## The audit history

Every application has a dedicated audit database recording what changed, who changed it, and when — kept separate from live data so operational activity can't disturb the record.

## Disclosure ledger for extensions

When a marketplace extension accesses tenant data, that access is written to a hash-chained ledger: each entry cryptographically commits to everything before it, so the record cannot be silently altered or trimmed after the fact. The exact code identity of the extension is snapshotted at invocation, so the ledger reflects precisely what ran. Tenants can verify their own ledger independently.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/trust/audit-and-disclosure.html).

---
title: "Tenant logging: the immutable record"
section: "Trust & Security"
canonical_url: "https://support.buildwithhq.com/trust/tenant-logging.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Tenant logging: the immutable record

A dedicated, append-only history of what happened — built so it can be verified, not just trusted.

## In brief

- **Where:** A dedicated logs database per application
- **Property:** Append-only, hash-chained
- **Related:** Replayable authorization

Every application's history lives in its own dedicated logs database, physically separate from live data. That separation is the first guarantee: heavy operational work can't disturb the record, and the record's growth can't slow the application. The rest of the guarantees are about what “immutable” actually means here.

## Append-only by design

The logs database is written to in exactly one way: new entries are appended. There are no update paths and no delete paths in the writing surface — history accumulates; it is never revised. Field-level access logging captures reads of sensitive data, not just writes, at a compliance grade suitable for regulated industries.

## Tamper-evident, not just tamper-resistant

For the most sensitive log families — AI data retrievals and third-party disclosures — append-only isn't considered enough, because append-only is a promise about behavior. These logs are **hash-chained**: each entry's fingerprint folds in the fingerprint of the entry before it, per tenant, so the entire history forms one continuous cryptographic braid. Alter, insert, or remove any entry anywhere in the chain and every subsequent fingerprint stops matching.

The consequence is the property that matters to an auditor: tampering isn't merely prohibited, it's **detectable by arithmetic**. A chain verification walks the history recomputing every link and reports the first break, if any exists. Trust becomes something you can check.

## Isolation between contexts

The logs database holds no security tables and makes no access decisions of its own — it accepts pre-resolved, pre-authorized entries from the platform layer, keeping the record's integrity concerns cleanly separated from live authorization concerns. Chains are maintained per tenant, so one tenant's history is cryptographically independent of every other's.

## What this buys you in practice

- **Dispute resolution** — “who saw this and when” has a definitive answer.
- **Compliance evidence** — an access history whose integrity can be demonstrated, not asserted.
- **Foundation for replay** — because the history is trustworthy, past security decisions can be re-examined against it. That's the next page: [replayable authorization](authorization-replay.html).
- **Tenant-owned analytics** — the active organization owner can configure export of selected log metadata to their own Snowflake account, subject to connection verification and explicit enablement. See [Snowflake analytics sync](../builder-guide/snowflake-analytics-sync.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/trust/tenant-logging.html).

---
title: "Replayable authorization: rewinding a security decision"
section: "Trust & Security"
canonical_url: "https://support.buildwithhq.com/trust/authorization-replay.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Replayable authorization: rewinding a security decision

Any past AI data access can be re-derived and re-checked — as of then, and as of now.

## In brief

- **Question answered:** “Was that access correct?” — provably
- **Modes:** As-of-then and as-of-now
- **Related:** Tenant logging

Most systems can tell you *that* data was accessed. Very few can prove the access was *correct* — that the permission rules, as they stood at that exact moment, genuinely allowed it. This platform can, because it keeps two things most systems throw away: a proof of each decision, and the history of the rules themselves.

## The proof: a sealed envelope per query

Every time the AI retrieves tenant data, the platform first resolves the complete set of records that user is allowed to see — their **security envelope** — and logs a cryptographic fingerprint of it, together with what was actually retrieved, into the tamper-evident chain described in [Tenant logging](tenant-logging.html). The decision isn't just made; it's notarized.

## The history: the rules remember themselves

The tables that permissions are computed from — user membership, roles, location assignments, and the records' own state — keep full, engine-native version history. The platform can therefore reconstruct *exactly what the rules said at any past instant*, the way you'd rewind a film to a frame.

## Replay: two questions, two modes

| Mode | Question it answers | What a failure means |
| --- | --- | --- |
| **As of then** | Re-derive the envelope under the rules *as they stood at that moment*. Does it match the logged proof, and was everything retrieved inside it? | Tampering, an enforcement bug, or a forged log entry — something that demands investigation. |
| **As of now** | Re-derive the envelope under *today's* rules. Would that same access still be permitted? | Not a violation — **drift**. Access that was proper then but wouldn't be today (a role change, a departure), which is exactly what a periodic review should surface. |

Each replay produces a recorded verdict — verified, mismatch, unauthorized retrieval, no longer authorized, or chain broken — and replays themselves are logged, so the checking is as accountable as the thing checked.

## Why this matters

When a customer, auditor, or regulator asks “did the AI ever access something it shouldn't have?”, the answer here isn't a policy document — it's a procedure: replay the period and read the verdicts. And the as-of-now mode turns the same machinery into hygiene, catching permission drift before anyone asks.

Note

The replayable window equals the retention of the rule history. Longer retention means further back you can rewind — a deliberate compliance dial, set per posture.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/trust/authorization-replay.html).

---
title: "Battle test: multiple tenants in a BuildWithHQ SaaS"
section: "Trust & Security"
canonical_url: "https://support.buildwithhq.com/trust/battle-test-2026-08-30.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Battle test: multiple tenants in a BuildWithHQ SaaS

How BuildWithHQ's first-class modules and APIs behaved with multiple tenants, scoped users, and hostile cross-tenant requests.

## In brief

- **Scenario:** Multiple tenants in one SaaS
- **Inventory:** 1,169 named passing tests
- **Result:** Security boundaries held

On August 30, 2026, we tested BuildWithHQ as a multi-tenant SaaS builders platform. Multiple tenant organizations operated inside the same SaaS while using different users, roles, DataRoles, locations, records, conversations, and support queues. The system worked within its designed boundaries: tenants remained separated, and each user could see or change only the information allowed by their server-derived identity and permissions.

## How the environment was used

**September 15 integrity follow-up:** A separate retained 20-organization test database passed 19 business and temporal invariants after the harness verified 24 zero-duration DataRole history boundary diagnostics. Those raw diagnostics remain in the evidence; unknown constraints, reversed periods, and positive-duration overlaps still fail. No business data or history was deleted. This bounded integrity check does not rerun or replace the historical load measurements below. Report unit tests now use isolated synthetic fixtures; missing real benchmark evidence still blocks performance sign-off.

The load scenario contained 1,000 synthetic organizations and 20,000 unique users. Every active user received a DataRole, User Type, and location assignment inside that user’s own organization. Each organization also had a non-deliverable `.example.test` support mailbox, customer contact, conversation, inbound message, reply, outbound-delivery state, and numbered support ticket. We used the platform as those organizations rather than only checking whether database objects existed. The workload included ordinary inbox traffic, ticket-enabled email addresses, message bursts, ticket resolution states, workflow actions, AI paths, integrations, record searches, and attempts to access another tenant’s data.

The SaaS used its normal three-database boundary: SaaS DB, SaaS Vector DB, and SaaS Immutable Logs. Builders, Template Library, and Platform Orchestration remained shared platform services and were not provisioned again for the SaaS.

## Browser and API load path

A real Chrome session signed in through the SaaS hostname, loaded its authorized Home page, opened Universal Inbox, selected Support Tickets, displayed ticket `SUP-000001`, and opened the Technical Support mailbox settings with Ticketing enabled. The cold post-restart sign-in and workspace bootstrap completed in 3.4 seconds in the test environment; opening Inbox took 20 ms, changing to Support Tickets took 249 ms, and loading mailbox ticketing settings took 601 ms. These measurements describe this test machine, not a production performance guarantee.

The authenticated HTTP sweep passed all 56 safe route and secured-record checks. A 200-request Universal Inbox run at concurrency eight returned 200 responses for every request, with a 19.6 ms median and 292 ms p95 response time.

## What was tested

Every current first-class module and API surface in the launch inventory was exercised at its applicable layers, including UI contracts, application services, stored procedures, database behavior, and live integration paths. Coverage included Universal Inbox, Support Tickets, GoClaw, AI retrieval, workflows, contacts, work orders, files, conversations, activity, search, knowledge, collaboration modules, integrations, marketplace behavior, provisioning, and operational workers.

- Valid users attempting to read or change another tenant’s records.
- Users attempting to widen their location, role, DataRole, named-action, or AI-read authority.
- Client-supplied tenant and record identifiers that did not match the authenticated server identity.
- Duplicate messages, ticket-number continuity, mailbox ticketing controls, stale Inbox/GoClaw context, workflow approvals, and replay behavior.
- Clean provisioning, generated API and stored-procedure contracts, seed consistency, rollback, and disposal of the three SaaS databases.

Across the tested first-class features and APIs, tenant separation held and record visibility followed each user’s role, DataRole, location, ownership, and explicit capabilities. AI retrieval respected the same record permissions, governed actions stayed behind their approval controls, and requests carrying another tenant’s identifiers were denied.

## Complete test inventory

The following 1,169 named tests all passed. Open any group to review every individual item.

**API gateway — 49 passed**
1. BuildWithHQ.ApiGateway.Tests.ApiResponseEnvelopeContractTests.AutomaticModelValidationUsesTheSharedErrorEnvelope
2. BuildWithHQ.ApiGateway.Tests.ApiResponseEnvelopeContractTests.EnvelopesRejectMissingCorrelationAndInvalidCodes
3. BuildWithHQ.ApiGateway.Tests.ApiResponseEnvelopeContractTests.ErrorEnvelopePreservesEstablishedFieldsAndStableDomainCode
4. BuildWithHQ.ApiGateway.Tests.ApiResponseEnvelopeContractTests.ProviderDiagnosticsAreNeverSerializedAsPublicErrors
5. BuildWithHQ.ApiGateway.Tests.ApiResponseEnvelopeContractTests.SuccessEnvelopeHasStableVersionDataAndCorrelationFields
6. BuildWithHQ.ApiGateway.Tests.ApiResponseEnvelopeContractTests.UnhandledExceptionsReturnOnlyGenericCorrelatedEnvelope
7. BuildWithHQ.ApiGateway.Tests.DeveloperAiControllerTests.ControllerExposesOnlyVersionedAppScopedAiRoutes
8. BuildWithHQ.ApiGateway.Tests.DeveloperAiControllerTests.PublicBodiesCannotSelectTenantPrincipalDatabaseOrProvider
9. BuildWithHQ.ApiGateway.Tests.DeveloperApiKeyAuthenticationTests.BearerCredentialCreatesOnlyServerResolvedServiceIdentity
10. BuildWithHQ.ApiGateway.Tests.DeveloperApiKeyAuthenticationTests.InvalidOrRevokedCredentialCannotCreateIdentity
11. BuildWithHQ.ApiGateway.Tests.DeveloperApiKeyAuthenticationTests.ScopeAccessorReadsOnlyAuthenticatedPrincipalClaims
12. BuildWithHQ.ApiGateway.Tests.DeveloperConnectorRegistryControllerTests.ControllerExposesOnlyAppScopedReadRoute
13. BuildWithHQ.ApiGateway.Tests.DeveloperConnectorRegistryControllerTests.ResponseCannotExposeTenantSecretsOrPhysicalRouting
14. BuildWithHQ.ApiGateway.Tests.DeveloperConnectorRegistryControllerTests.ResponseMapsTheVersionedRegistryAndStableSideEffectNames
15. BuildWithHQ.ApiGateway.Tests.DeveloperDataConnectorsControllerTests.ControllerExposesAccountScopedConnectorLifecycle
16. BuildWithHQ.ApiGateway.Tests.DeveloperDataConnectorsControllerTests.RequestBodyCannotSelectPrincipalScopePhysicalRoutingOrRawSecret
17. BuildWithHQ.ApiGateway.Tests.DeveloperDatabaseContractsTests.ControllerIsAuthenticatedAppScopedAndReadOnly
18. BuildWithHQ.ApiGateway.Tests.DeveloperDatabaseContractsTests.EmbeddedCatalogReturnsOnlyLogicalTenantFingerprints
19. BuildWithHQ.ApiGateway.Tests.DeveloperDatabaseContractsTests.ServiceRequiresExactServerIdentityAndTenantAccount
20. BuildWithHQ.ApiGateway.Tests.DeveloperInboundEndpointsControllerTests.ControllerExposesVersionedEndpointKeyLifecycle
21. BuildWithHQ.ApiGateway.Tests.DeveloperInboundEndpointsControllerTests.RequestBodyCannotSelectTenantPrincipalOrPhysicalDatabase
22. BuildWithHQ.ApiGateway.Tests.DeveloperInstalledServicesControllerTests.ControllerExposesOnlyLogicalInstalledServiceInvocationRoute
23. BuildWithHQ.ApiGateway.Tests.DeveloperInstalledServicesControllerTests.RequestBodyCannotSelectTenantIdentityOrPhysicalRouting
24. BuildWithHQ.ApiGateway.Tests.DeveloperLogsControllerTests.ControllerExposesOnlyVersionedAppScopedReadRoutes
25. BuildWithHQ.ApiGateway.Tests.DeveloperLogsControllerTests.PublicInputsCannotSelectAccountDatabaseProviderOrCredential
26. BuildWithHQ.ApiGateway.Tests.DeveloperLogsServiceTests.CrossAppIdentityFailsBeforeDatabaseRouting
27. BuildWithHQ.ApiGateway.Tests.DeveloperLogsServiceTests.QueryUsesOnlyServerIdentityAndStoredProcedure
28. BuildWithHQ.ApiGateway.Tests.DeveloperMcpServerTests.InvalidSensitiveCapabilityConfigurationFailsStartup
29. BuildWithHQ.ApiGateway.Tests.DeveloperMcpServerTests.OfficialSdkBuildsAllPublicToolSchemas
30. BuildWithHQ.ApiGateway.Tests.DeveloperMcpServerTests.ReadToolRequiresMcpAndRestScopesForTheSameRouteApp
31. BuildWithHQ.ApiGateway.Tests.DeveloperMcpServerTests.SensitiveToolsAreDefaultDeniedAndRequireServerApproval
32. BuildWithHQ.ApiGateway.Tests.DeveloperMcpServerTests.ToolCatalogExactlyMatchesTheServerPolicy
33. BuildWithHQ.ApiGateway.Tests.DeveloperMcpServerTests.UnauthenticatedAndMalformedRoutesExposeNoTools
34. BuildWithHQ.ApiGateway.Tests.DeveloperOAuthConnectionsControllerTests.ControllerPublishesTheCompleteOAuthLifecycle
35. BuildWithHQ.ApiGateway.Tests.DeveloperOAuthConnectionsControllerTests.RequestDtosCannotSelectIdentityProviderConfigurationTokensOrPhysicalRouting
36. BuildWithHQ.ApiGateway.Tests.DeveloperPaymentConnectorsControllerTests.ControllerExposesAccountScopedPaymentConnectorLifecycle
37. BuildWithHQ.ApiGateway.Tests.DeveloperPaymentConnectorsControllerTests.RequestBodyCannotSelectPrincipalRoutingProviderEndpointOrRawSecret
38. BuildWithHQ.ApiGateway.Tests.DeveloperRecordsControllerTests.PublicRoutesAndBodiesCannotSelectTenantPrincipalOrPhysicalDatabase
39. BuildWithHQ.ApiGateway.Tests.DeveloperRecordsControllerTests.RecordsControllerExposesTheVersionedHeadlessSurface
40. BuildWithHQ.ApiGateway.Tests.DeveloperWebhookDeliveriesControllerTests.ControllerExposesOnlyTenantScopedListAndRetryRoutes
41. BuildWithHQ.ApiGateway.Tests.DeveloperWebhookSubscriptionsControllerTests.ControllerExposesVersionedSubscriptionSurfaceWithoutRoutingSelectors
42. BuildWithHQ.ApiGateway.Tests.GatewayMetadataControllerTests.MetadataAndHealthExposeStableAnonymousRoutes
43. BuildWithHQ.ApiGateway.Tests.GatewayMetadataControllerTests.MetadataUsesMiddlewareCorrelationAndExposesNoTopology
44. BuildWithHQ.ApiGateway.Tests.WebSecurityTests.BearerAndApiKeyRequestsDoNotRequireCsrf
45. BuildWithHQ.ApiGateway.Tests.WebSecurityTests.MissingOrCrossOriginCookieProofIsDeniedBeforeController
46. BuildWithHQ.ApiGateway.Tests.WebSecurityTests.OriginConfigurationIsExactAndProductionFailsClosed
47. BuildWithHQ.ApiGateway.Tests.WebSecurityTests.SecurityHeadersAreAppliedToEveryResponse
48. BuildWithHQ.ApiGateway.Tests.WebSecurityTests.UnsafeCookieRequestRequiresAllowedOriginAndMatchingToken
49. BuildWithHQ.ApiGateway.Tests.WebSecurityTests.WildcardAndInsecureRemoteOriginsAreRejected

**Tenant runtime and first-class modules — 225 passed**
1. BuildWithHQ.TenantRuntime.Tests.PagePublicationContractTests.AuthoritativePublishProcedureRevalidatesBeforeLiveUpdate
2. BuildWithHQ.TenantRuntime.Tests.PagePublicationContractTests.DataBindingsResolveByServerScopeAndUnknownKeysBlockPublish
3. BuildWithHQ.TenantRuntime.Tests.PagePublicationContractTests.PublishedRuntimeSnapshotIsIsolatedFromCurrentDraftHistory
4. BuildWithHQ.TenantRuntime.Tests.PagePublicationContractTests.RawDraftSaveWrappersValidateBeforeAnyPageWrite
5. BuildWithHQ.TenantRuntime.Tests.PagePublicationContractTests.RuntimeBootstrapUsesEffectiveAuthorizedComponentRegistry
6. BuildWithHQ.TenantRuntime.Tests.PagePublicationContractTests.RuntimeMetadataComesFromTheSameAuthorizedEffectivePage
7. BuildWithHQ.TenantRuntime.Tests.PagePublicationContractTests.RuntimeRendererGrammarMatchesAuthoritativePageValidator
8. BuildWithHQ.TenantRuntime.Tests.PagePublicationContractTests.TenantRevisionSaveCannotPublishInvalidPresentationJson
9. BuildWithHQ.TenantRuntime.Tests.TenantActiveWorkplaceLiveDatabaseTests.LiveActiveWorkplaceRejectsGoClawWithoutIndependentAiRead
10. BuildWithHQ.TenantRuntime.Tests.TenantActiveWorkplaceLiveDatabaseTests.LiveActiveWorkplaceSecuresGraphParticipantsPulseInboxAndPlayback
11. BuildWithHQ.TenantRuntime.Tests.TenantActiveWorkplaceServiceTests.ControllerAndMigrationEnforceSecurityAndReadOnlyPlayback
12. BuildWithHQ.TenantRuntime.Tests.TenantActiveWorkplaceServiceTests.CreateAndReadUseServerScopeAndReviewedProcedures
13. BuildWithHQ.TenantRuntime.Tests.TenantActiveWorkplaceServiceTests.ParticipantsActivityAndPlaybackStayInsideContracts
14. BuildWithHQ.TenantRuntime.Tests.TenantAssetsServiceTests.ActiveContentAndTraversalNamesFailBeforeStorageOrDatabase
15. BuildWithHQ.TenantRuntime.Tests.TenantAssetsServiceTests.ControllerAndMigrationEnforceSecuredAccountAssets
16. BuildWithHQ.TenantRuntime.Tests.TenantAssetsServiceTests.FailedRegistrationCompensatesStoredContent
17. BuildWithHQ.TenantRuntime.Tests.TenantAssetsServiceTests.ListUploadContentAndDeleteUseOnlyVerifiedTenantScope
18. BuildWithHQ.TenantRuntime.Tests.TenantCalendarLiveDatabaseTests.LiveGoldenCalendarRejectsCreateWithoutCanCreateAndLeavesNoRecord
19. BuildWithHQ.TenantRuntime.Tests.TenantCalendarLiveDatabaseTests.LiveGoldenCalendarRespectsSecurityPrivacyAndUniversalRecords
20. BuildWithHQ.TenantRuntime.Tests.TenantCalendarServiceTests.ControllerIsAuthenticatedAndAcceptsNoCallerControlledScope
21. BuildWithHQ.TenantRuntime.Tests.TenantCalendarServiceTests.CreateAndUpdateUseTypedDynamicFieldsAndConcurrencyFence
22. BuildWithHQ.TenantRuntime.Tests.TenantCalendarServiceTests.FactoryRejectsHostTokenMismatchBeforeTenantRouting
23. BuildWithHQ.TenantRuntime.Tests.TenantCalendarServiceTests.FavoriteUsesUniversalRecordIdentityAndServerScope
24. BuildWithHQ.TenantRuntime.Tests.TenantCalendarServiceTests.InvalidWritesFailBeforeDatabaseWithRequestCorrelation
25. BuildWithHQ.TenantRuntime.Tests.TenantCalendarServiceTests.ListUsesOnlyServerDerivedScopeAndParsesUniversalRecords
26. BuildWithHQ.TenantRuntime.Tests.TenantCalendarServiceTests.MigrationEnforcesSaasRoleLocationPrivacyDynamicAndUniversalRecordContracts
27. BuildWithHQ.TenantRuntime.Tests.TenantChatRoomsLiveDatabaseTests.LiveGoldenChatRoomsRejectsPostingWithoutMembershipAndLeavesNoMessage
28. BuildWithHQ.TenantRuntime.Tests.TenantChatRoomsLiveDatabaseTests.LiveGoldenChatRoomsRejectsWrongLocalSaasIdentity
29. BuildWithHQ.TenantRuntime.Tests.TenantChatRoomsLiveDatabaseTests.LiveGoldenChatRoomsRespectsSaasRoleLocationMembershipAndUniversalRecords
30. BuildWithHQ.TenantRuntime.Tests.TenantChatRoomsServiceTests.CollaborationActionsUseRecordTargetsAndServerIdentity
31. BuildWithHQ.TenantRuntime.Tests.TenantChatRoomsServiceTests.ControllerAndMigrationKeepAuthorizationOnServer
32. BuildWithHQ.TenantRuntime.Tests.TenantChatRoomsServiceTests.FactoryRejectsHostTokenMismatchBeforeTenantRouting
33. BuildWithHQ.TenantRuntime.Tests.TenantChatRoomsServiceTests.InvalidMessagesAndReactionsFailBeforeDatabase
34. BuildWithHQ.TenantRuntime.Tests.TenantChatRoomsServiceTests.ListUsesOnlyServerDerivedScopeAndParsesMembershipState
35. BuildWithHQ.TenantRuntime.Tests.TenantChatRoomsServiceTests.RoomWritesUseDynamicFieldsAndOptimisticConcurrency
36. BuildWithHQ.TenantRuntime.Tests.TenantCompanyNewsLiveDatabaseTests.LiveGoldenCompanyNewsRejectsCreateWithoutCanCreateAndLeavesNoRecord
37. BuildWithHQ.TenantRuntime.Tests.TenantCompanyNewsLiveDatabaseTests.LiveGoldenCompanyNewsRespectsSaasRoleLocationPublishingAndUniversalRecords
38. BuildWithHQ.TenantRuntime.Tests.TenantCompanyNewsServiceTests.ControllerAndMigrationKeepScopeOnTheServerAndUseUniversalFeatures
39. BuildWithHQ.TenantRuntime.Tests.TenantCompanyNewsServiceTests.CreateAndUpdateUseTypedDynamicFieldsAndConcurrencyFence
40. BuildWithHQ.TenantRuntime.Tests.TenantCompanyNewsServiceTests.FactoryRejectsHostTokenMismatchBeforeTenantRouting
41. BuildWithHQ.TenantRuntime.Tests.TenantCompanyNewsServiceTests.FavoriteUsesUniversalRecordIdentityAndServerScope
42. BuildWithHQ.TenantRuntime.Tests.TenantCompanyNewsServiceTests.InvalidWritesFailBeforeDatabaseWithRequestCorrelation
43. BuildWithHQ.TenantRuntime.Tests.TenantCompanyNewsServiceTests.ListUsesOnlyServerDerivedScopeAndParsesUniversalRecords
44. BuildWithHQ.TenantRuntime.Tests.TenantContactsLiveDatabaseTests.LiveGoldenContactsRespectSecurityAndUniversalRecordContracts
45. BuildWithHQ.TenantRuntime.Tests.TenantContactsServiceTests.ControllerIsAuthenticatedAndAcceptsNoCallerControlledScope
46. BuildWithHQ.TenantRuntime.Tests.TenantContactsServiceTests.CreateAndUpdateUseTypedDynamicFieldsAndConcurrencyFence
47. BuildWithHQ.TenantRuntime.Tests.TenantContactsServiceTests.FactoryRejectsHostTokenMismatchBeforeTenantRouting
48. BuildWithHQ.TenantRuntime.Tests.TenantContactsServiceTests.FavoriteUsesUniversalRecordIdentityAndServerScope
49. BuildWithHQ.TenantRuntime.Tests.TenantContactsServiceTests.InvalidWritesFailBeforeDatabaseWithRequestCorrelation
50. BuildWithHQ.TenantRuntime.Tests.TenantContactsServiceTests.ListUsesOnlyServerDerivedScopeAndParsesUniversalRecords
51. BuildWithHQ.TenantRuntime.Tests.TenantContactsServiceTests.MigrationEnforcesSaasRoleLocationDynamicAndUniversalRecordContracts
52. BuildWithHQ.TenantRuntime.Tests.TenantConversationsLiveDatabaseTests.LiveGoldenConversationsRejectReadOnlyReply
53. BuildWithHQ.TenantRuntime.Tests.TenantConversationsLiveDatabaseTests.LiveGoldenConversationsRespectSaasLocationRolesAndUniversalRecords
54. BuildWithHQ.TenantRuntime.Tests.TenantConversationsServiceTests.ControllerIsAuthenticatedAndAcceptsNoCallerScope
55. BuildWithHQ.TenantRuntime.Tests.TenantConversationsServiceTests.CreateUpdateReplyAndFavoriteUseReviewedContracts
56. BuildWithHQ.TenantRuntime.Tests.TenantConversationsServiceTests.DetailUsesUniversalRecordAndReadOnlyJsonContract
57. BuildWithHQ.TenantRuntime.Tests.TenantConversationsServiceTests.FactoryRejectsHostTokenMismatchBeforeTenantRouting
58. BuildWithHQ.TenantRuntime.Tests.TenantConversationsServiceTests.InvalidStatusAndMessageFailBeforeDatabaseWithCorrelation
59. BuildWithHQ.TenantRuntime.Tests.TenantConversationsServiceTests.ListUsesOnlyServerScopeAndParsesUniversalRecords
60. BuildWithHQ.TenantRuntime.Tests.TenantConversationsServiceTests.MalformedDatabaseJsonFailsClosedWithCorrelation
61. BuildWithHQ.TenantRuntime.Tests.TenantConversationsServiceTests.MigrationUsesNativePipelineAndSecuresUniversalScopeWithoutMutatingOnRead
62. BuildWithHQ.TenantRuntime.Tests.TenantDataBindingServiceTests.ControllerMapsMissingBindingToSafeCorrelatedResponse
63. BuildWithHQ.TenantRuntime.Tests.TenantDataBindingServiceTests.EndpointIsAuthenticatedReadOnlyAndAcceptsOnlyBindingKey
64. BuildWithHQ.TenantRuntime.Tests.TenantDataBindingServiceTests.ExecutesOnlyResolvedReviewedProcedureWithServerContext
65. BuildWithHQ.TenantRuntime.Tests.TenantDataBindingServiceTests.UnknownBindingAndHostMismatchFailClosed
66. BuildWithHQ.TenantRuntime.Tests.TenantDataBindingServiceTests.UnsafeOrUnscopedOperationFailsBeforeExecution
67. BuildWithHQ.TenantRuntime.Tests.TenantDataBindingServiceTests.UnsupportedConnectorAndOutputShapeFailClosed
68. BuildWithHQ.TenantRuntime.Tests.TenantDataChatServiceTests.ControllerIsAuthorizedTypedAndCannotAcceptDatabaseIdentity
69. BuildWithHQ.TenantRuntime.Tests.TenantDataChatServiceTests.ControllerReturnsSafe503WhenReviewedModelCapacityIsDeferred
70. BuildWithHQ.TenantRuntime.Tests.TenantDataChatServiceTests.FactoryRejectsHostTokenMismatchBeforeTenantDatabaseRouting
71. BuildWithHQ.TenantRuntime.Tests.TenantDiscussionBoardsLiveDatabaseTests.LiveGoldenDiscussionBoardsRejectsLockedTopicReplyAndLeavesNoPost
72. BuildWithHQ.TenantRuntime.Tests.TenantDiscussionBoardsLiveDatabaseTests.LiveGoldenDiscussionBoardsRejectsWrongLocalSaasIdentity
73. BuildWithHQ.TenantRuntime.Tests.TenantDiscussionBoardsLiveDatabaseTests.LiveGoldenDiscussionBoardsRespectsSaasRoleLocationAndUniversalRecords
74. BuildWithHQ.TenantRuntime.Tests.TenantDiscussionBoardsServiceTests.BoardWritesUseDynamicFieldsAndOptimisticConcurrency
75. BuildWithHQ.TenantRuntime.Tests.TenantDiscussionBoardsServiceTests.ControllerAndMigrationKeepAuthorizationOnServer
76. BuildWithHQ.TenantRuntime.Tests.TenantDiscussionBoardsServiceTests.FactoryRejectsHostTokenMismatchBeforeTenantRouting
77. BuildWithHQ.TenantRuntime.Tests.TenantDiscussionBoardsServiceTests.InvalidBodiesAndConcurrencyFailBeforeDatabase
78. BuildWithHQ.TenantRuntime.Tests.TenantDiscussionBoardsServiceTests.ListUsesOnlyServerDerivedScopeAndParsesCounts
79. BuildWithHQ.TenantRuntime.Tests.TenantDiscussionBoardsServiceTests.TopicPostAndFavoriteActionsUseRecordTargets
80. BuildWithHQ.TenantRuntime.Tests.TenantDynamicModulesServiceTests.ControllerAndSqlKeepScopeServerSideAndCustomOnly
81. BuildWithHQ.TenantRuntime.Tests.TenantDynamicModulesServiceTests.CreateSerializesTypedFieldsAndCorrelation
82. BuildWithHQ.TenantRuntime.Tests.TenantDynamicModulesServiceTests.InvalidModuleKeyFailsBeforeDatabase
83. BuildWithHQ.TenantRuntime.Tests.TenantDynamicModulesServiceTests.ListUsesOnlyServerScopeAndConfiguredModuleKey
84. BuildWithHQ.TenantRuntime.Tests.TenantFavoritesLiveDatabaseTests.LiveGoldenFavoritesRejectAnotherUsersFavorite
85. BuildWithHQ.TenantRuntime.Tests.TenantFavoritesLiveDatabaseTests.LiveGoldenFavoritesRejectWrongLocalSaasIdentity
86. BuildWithHQ.TenantRuntime.Tests.TenantFavoritesLiveDatabaseTests.LiveGoldenFavoritesRespectSaasUserRoleLocationAndUniversalRecords
87. BuildWithHQ.TenantRuntime.Tests.TenantFavoritesServiceTests.ControllerAndMigrationKeepFavoriteOwnershipAndAuthorizationBoundaries
88. BuildWithHQ.TenantRuntime.Tests.TenantFavoritesServiceTests.FactoryRejectsHostTokenMismatchBeforeTenantRouting
89. BuildWithHQ.TenantRuntime.Tests.TenantFavoritesServiceTests.InvalidFiltersAndTargetsFailBeforeDatabase
90. BuildWithHQ.TenantRuntime.Tests.TenantFavoritesServiceTests.ListUsesOnlyServerScopeAndParsesRecordFavorites
91. BuildWithHQ.TenantRuntime.Tests.TenantFavoritesServiceTests.MutationsUseUniversalRecordTargets
92. BuildWithHQ.TenantRuntime.Tests.TenantFilesLiveDatabaseTests.LiveGoldenFilesRejectCreateWithoutCanCreateAndLeaveNoRecord
93. BuildWithHQ.TenantRuntime.Tests.TenantFilesLiveDatabaseTests.LiveGoldenFilesRespectSecurityStorageAndUniversalRecords
94. BuildWithHQ.TenantRuntime.Tests.TenantFilesServiceTests.ControllerIsAuthenticatedAndAcceptsNoCallerScopeOrStorageKey
95. BuildWithHQ.TenantRuntime.Tests.TenantFilesServiceTests.DownloadResolvesStorageOnlyAfterSecuredDatabaseContract
96. BuildWithHQ.TenantRuntime.Tests.TenantFilesServiceTests.FactoryRejectsHostTokenMismatchBeforeTenantRouting
97. BuildWithHQ.TenantRuntime.Tests.TenantFilesServiceTests.FailedDatabaseRegistrationCompensatesStoredBytes
98. BuildWithHQ.TenantRuntime.Tests.TenantFilesServiceTests.InvalidUploadFailsBeforeStorageOrDatabaseWithCorrelation
99. BuildWithHQ.TenantRuntime.Tests.TenantFilesServiceTests.ListUsesOnlyServerDerivedScopeAndParsesUniversalRecords
100. BuildWithHQ.TenantRuntime.Tests.TenantFilesServiceTests.LocalStorageRejectsTraversalAndRoundTripsScopedBytes
101. BuildWithHQ.TenantRuntime.Tests.TenantFilesServiceTests.MigrationEnforcesSaasRoleLocationDynamicAttachmentsAndUniversalRecords
102. BuildWithHQ.TenantRuntime.Tests.TenantFilesServiceTests.MutationsUseUniversalIdentityConcurrencyAndAttachmentContracts
103. BuildWithHQ.TenantRuntime.Tests.TenantFilesServiceTests.UploadStoresBytesThenUsesReviewedMetadataContract
104. BuildWithHQ.TenantRuntime.Tests.TenantFormsServiceTests.AFormNotPresentOnTheAuthorizedPageNeverSubmits
105. BuildWithHQ.TenantRuntime.Tests.TenantFormsServiceTests.ControllerIsAuthenticatedAndAcceptsNoCallerControlledIdentity
106. BuildWithHQ.TenantRuntime.Tests.TenantFormsServiceTests.InvalidOrUnknownValuesFailBeforeDatabaseMutation
107. BuildWithHQ.TenantRuntime.Tests.TenantFormsServiceTests.MigrationRegistersFirstClassFormAndOnlyGrantsTheSubmissionProcedure
108. BuildWithHQ.TenantRuntime.Tests.TenantFormsServiceTests.PublishedFormEventActionsAreValidatedAndForwardedWithoutAuthorityFields
109. BuildWithHQ.TenantRuntime.Tests.TenantFormsServiceTests.SubmissionReloadsAuthorizedPageAndUsesOnlyServerDerivedScope
110. BuildWithHQ.TenantRuntime.Tests.TenantGlobalSearchLiveDatabaseTests.LiveGoldenGlobalSearchRejectsWrongSaas
111. BuildWithHQ.TenantRuntime.Tests.TenantGlobalSearchLiveDatabaseTests.LiveGoldenGlobalSearchSecuresRecordsFieldsAndMetadata
112. BuildWithHQ.TenantRuntime.Tests.TenantGlobalSearchServiceTests.ControllerAndMigrationKeepGlobalSearchAuthorizationBoundaries
113. BuildWithHQ.TenantRuntime.Tests.TenantGlobalSearchServiceTests.FactoryRejectsHostTokenMismatch
114. BuildWithHQ.TenantRuntime.Tests.TenantGlobalSearchServiceTests.FavoriteUsesCanonicalRecordIdentity
115. BuildWithHQ.TenantRuntime.Tests.TenantGlobalSearchServiceTests.InvalidBoundsFailBeforeDatabase
116. BuildWithHQ.TenantRuntime.Tests.TenantGlobalSearchServiceTests.SearchUsesOnlyServerScopeAndParsesMatchedFields
117. BuildWithHQ.TenantRuntime.Tests.TenantGoClawApprovalsControllerTests.EndpointIsAuthenticatedAndHasNoCallerIdentityFields
118. BuildWithHQ.TenantRuntime.Tests.TenantGoClawApprovalsControllerTests.EndpointReturnsTypedBatchesAndDisablesCaching
119. BuildWithHQ.TenantRuntime.Tests.TenantGoClawApprovalsControllerTests.EndpointRoutesReviewerEditsAndRejectsWithoutCallerIdentity
120. BuildWithHQ.TenantRuntime.Tests.TenantGoClawApprovalsControllerTests.FactoryRoutesOnlyTheThreeApprovalContracts
121. BuildWithHQ.TenantRuntime.Tests.TenantGoClawApprovalsControllerTests.HostAndTokenMismatchFailsBeforeTenantDatabaseRouting
122. BuildWithHQ.TenantRuntime.Tests.TenantGoClawAuthorityControllerTests.ConfigureUsesHostScopedFactoryAndTypedPolicyService
123. BuildWithHQ.TenantRuntime.Tests.TenantInboundSmsServiceTests.ControllerIsAnonymousOnlyAtSignedWebhookAndMigrationReturnsNoSecret
124. BuildWithHQ.TenantRuntime.Tests.TenantInboundSmsServiceTests.DatabaseFailuresAreMappedToControllerSafeDependencyError
125. BuildWithHQ.TenantRuntime.Tests.TenantInboundSmsServiceTests.InvalidSignatureNeverInvokesCanonicalIngest
126. BuildWithHQ.TenantRuntime.Tests.TenantInboundSmsServiceTests.MissingSecretReferenceFailsClosedBeforeIngest
127. BuildWithHQ.TenantRuntime.Tests.TenantInboundSmsServiceTests.TwilioProtocolVectorAndConstantTimeInputContractMatch
128. BuildWithHQ.TenantRuntime.Tests.TenantInboundSmsServiceTests.ValidSignedMmsUsesOnlyReviewedContractsAndServerSaasApp
129. BuildWithHQ.TenantRuntime.Tests.TenantKnowledgeArticlesLiveDatabaseTests.LiveGoldenKnowledgeArticlesRejectCreateWithoutCanCreateAndLeaveNoRecord
130. BuildWithHQ.TenantRuntime.Tests.TenantKnowledgeArticlesLiveDatabaseTests.LiveGoldenKnowledgeArticlesRespectSaasRoleLocationPublishingAndUniversalRecords
131. BuildWithHQ.TenantRuntime.Tests.TenantKnowledgeArticlesServiceTests.ControllerAndMigrationKeepScopeOnTheServerAndUseUniversalFeatures
132. BuildWithHQ.TenantRuntime.Tests.TenantKnowledgeArticlesServiceTests.CreateAndUpdateUseTypedDynamicFieldsAndConcurrencyFence
133. BuildWithHQ.TenantRuntime.Tests.TenantKnowledgeArticlesServiceTests.FactoryRejectsHostTokenMismatchBeforeTenantRouting
134. BuildWithHQ.TenantRuntime.Tests.TenantKnowledgeArticlesServiceTests.FavoriteUsesUniversalRecordIdentityAndServerScope
135. BuildWithHQ.TenantRuntime.Tests.TenantKnowledgeArticlesServiceTests.InvalidWritesFailBeforeDatabaseWithRequestCorrelation
136. BuildWithHQ.TenantRuntime.Tests.TenantKnowledgeArticlesServiceTests.ListUsesOnlyServerDerivedScopeAndParsesUniversalRecords
137. BuildWithHQ.TenantRuntime.Tests.TenantMailReaderLiveDatabaseTests.LiveGoldenMailReaderRejectsSharedReadMutationWithoutEditAndLeavesUnread
138. BuildWithHQ.TenantRuntime.Tests.TenantMailReaderLiveDatabaseTests.LiveGoldenMailReaderRejectsWrongLocalSaasIdentity
139. BuildWithHQ.TenantRuntime.Tests.TenantMailReaderLiveDatabaseTests.LiveGoldenMailReaderRespectsSaasRoleLocationOwnershipAndUniversalRecords
140. BuildWithHQ.TenantRuntime.Tests.TenantMailReaderServiceTests.ControllerAndMigrationKeepMailAndAuthorizationBoundaries
141. BuildWithHQ.TenantRuntime.Tests.TenantMailReaderServiceTests.FactoryRejectsHostTokenMismatchBeforeTenantRouting
142. BuildWithHQ.TenantRuntime.Tests.TenantMailReaderServiceTests.InvalidFiltersAndTargetsFailBeforeDatabase
143. BuildWithHQ.TenantRuntime.Tests.TenantMailReaderServiceTests.ListUsesOnlyServerScopeAndParsesAccounts
144. BuildWithHQ.TenantRuntime.Tests.TenantMailReaderServiceTests.ReadAndFavoriteMutationsUseRecordTargets
145. BuildWithHQ.TenantRuntime.Tests.TenantNotificationsServiceTests.ControllerAndMigrationKeepScopeServerSideAndSecureSourceRecords
146. BuildWithHQ.TenantRuntime.Tests.TenantNotificationsServiceTests.FactoryRejectsHostTokenMismatchBeforeTenantRouting
147. BuildWithHQ.TenantRuntime.Tests.TenantNotificationsServiceTests.InvalidRequestsFailBeforeDatabaseWithRequestCorrelation
148. BuildWithHQ.TenantRuntime.Tests.TenantNotificationsServiceTests.ListUsesOnlyServerDerivedRecipientAndTenantScope
149. BuildWithHQ.TenantRuntime.Tests.TenantNotificationsServiceTests.StateAndSourceFavoriteUseNotificationIdentityInsideServerScope
150. BuildWithHQ.TenantRuntime.Tests.TenantPageAdoptionTests.ControllerAndGrantsExposeNoCallerControlledIdentity
151. BuildWithHQ.TenantRuntime.Tests.TenantPageAdoptionTests.DriftAndAdoptionUseScopedThreeWayEvidenceAndCurrentLease
152. BuildWithHQ.TenantRuntime.Tests.TenantPageAdoptionTests.DriftListUsesVerifiedAccountAndNeverMutatesPrivatePages
153. BuildWithHQ.TenantRuntime.Tests.TenantPageAdoptionTests.StaleEvidenceStopsBeforeLockOrMutation
154. BuildWithHQ.TenantRuntime.Tests.TenantPageAdoptionTests.UndoRequiresOwnerLeaseBeforeReviewedProcedure
155. BuildWithHQ.TenantRuntime.Tests.TenantPageEditLockTests.AcquireAndRenewForceServerDerivedForkLease
156. BuildWithHQ.TenantRuntime.Tests.TenantPageEditLockTests.ConflictingEditorIsDeniedWithoutExposingTheirIdentity
157. BuildWithHQ.TenantRuntime.Tests.TenantPageEditLockTests.ControllerIsAuthenticatedAndAcceptsNoLockScopeOrIdentity
158. BuildWithHQ.TenantRuntime.Tests.TenantPageEditLockTests.MigrationMakesFirstForkLeaseAtomicAndSaveEnforcesIt
159. BuildWithHQ.TenantRuntime.Tests.TenantPageEditLockTests.ReleaseCanOnlyTargetTheCurrentUsersForkLock
160. BuildWithHQ.TenantRuntime.Tests.TenantPageRevisionsServiceTests.ControllerRequiresAuthenticationAndAcceptsNoScopeIdentifiers
161. BuildWithHQ.TenantRuntime.Tests.TenantPageRevisionsServiceTests.HistoryAndSnapshotUseOnlyServerDerivedTenantScope
162. BuildWithHQ.TenantRuntime.Tests.TenantPageRevisionsServiceTests.InvalidHistoricalJsonCannotBecomeTheLiveTenantPage
163. BuildWithHQ.TenantRuntime.Tests.TenantPageRevisionsServiceTests.RestoreAuthorizesSnapshotBeforeMutationAndChecksReturnedScope
164. BuildWithHQ.TenantRuntime.Tests.TenantPageRevisionsServiceTests.RuntimeRoleMigrationGrantsOnlyReviewedRevisionProcedures
165. BuildWithHQ.TenantRuntime.Tests.TenantPageRevisionsServiceTests.SaveKeepsIdentityAndDatabaseRoutingOffTheClientContract
166. BuildWithHQ.TenantRuntime.Tests.TenantPageRevisionsServiceTests.UnknownSnapshotNeverReachesPreviewOrRestoreProcedure
167. BuildWithHQ.TenantRuntime.Tests.TenantPageRouteServiceTests.AnonymousContextAndInvalidSlugCannotReachEitherDatabase
168. BuildWithHQ.TenantRuntime.Tests.TenantPageRouteServiceTests.CanonicalBootstrapAuthorizationAndJsonFailuresCannotEscapeTheRoute
169. BuildWithHQ.TenantRuntime.Tests.TenantPageRouteServiceTests.MissingOrMalformedSlugResultFailsClosed
170. BuildWithHQ.TenantRuntime.Tests.TenantPageRouteServiceTests.ResolvesOnlyPageKeyThenLoadsAuthorizedCanonicalBootstrap
171. BuildWithHQ.TenantRuntime.Tests.TenantPageRouteServiceTests.RouteEndpointIsAuthenticatedReadOnlyAndReturnsSafeErrors
172. BuildWithHQ.TenantRuntime.Tests.TenantPageServiceTests.AnonymousOrBuilderContextCannotReachEitherDatabase
173. BuildWithHQ.TenantRuntime.Tests.TenantPageServiceTests.BootstrapMetadataCannotSubstituteCallerIdentity
174. BuildWithHQ.TenantRuntime.Tests.TenantPageServiceTests.ControllerAuditsAuthorizedBootstrapBeforeReturningIt
175. BuildWithHQ.TenantRuntime.Tests.TenantPageServiceTests.ControllerMapsMissingPageToSafeCorrelatedResponse
176. BuildWithHQ.TenantRuntime.Tests.TenantPageServiceTests.EndpointIsAuthenticatedReadOnlyAndHasNoCallerScopeFields
177. BuildWithHQ.TenantRuntime.Tests.TenantPageServiceTests.HostAndTokenAppMismatchFailsClosedBeforeTenantRouting
178. BuildWithHQ.TenantRuntime.Tests.TenantPageServiceTests.InvalidComponentManifestCannotBecomeClientRuntimeState
179. BuildWithHQ.TenantRuntime.Tests.TenantPageServiceTests.InvalidRuntimePresentationPayloadFailsClosed
180. BuildWithHQ.TenantRuntime.Tests.TenantPageServiceTests.LoadsCanonicalBootstrapWithOnlyServerDerivedTenantScope
181. BuildWithHQ.TenantRuntime.Tests.TenantPageServiceTests.MalformedShellCannotBecomeClientRuntimeState
182. BuildWithHQ.TenantRuntime.Tests.TenantPageServiceTests.TenantJwtGateRejectsWrongPlaneAndAmbiguousIdentity
183. BuildWithHQ.TenantRuntime.Tests.TenantPaymentsServiceTests.ChargeUsesOnlyServerScopeAndReviewedProcedure
184. BuildWithHQ.TenantRuntime.Tests.TenantPaymentsServiceTests.ControllerAndMigrationPreserveTenantProcedureBoundary
185. BuildWithHQ.TenantRuntime.Tests.TenantPaymentsServiceTests.InvalidPolicyAndRawCardShapesFailBeforeDatabaseAccess
186. BuildWithHQ.TenantRuntime.Tests.TenantRecordActivityLiveDatabaseTests.LiveGoldenRecordActivityRejectsWrongSaas
187. BuildWithHQ.TenantRuntime.Tests.TenantRecordActivityLiveDatabaseTests.LiveGoldenRecordActivityRequiresAiReadPermission
188. BuildWithHQ.TenantRuntime.Tests.TenantRecordActivityLiveDatabaseTests.LiveGoldenRecordActivitySecuresTimelineHistoryAndMetadata
189. BuildWithHQ.TenantRuntime.Tests.TenantRecordActivityServiceTests.ControllerAndMigrationKeepActivityAuthorizationBoundaries
190. BuildWithHQ.TenantRuntime.Tests.TenantRecordActivityServiceTests.FactoryRejectsHostTokenMismatch
191. BuildWithHQ.TenantRuntime.Tests.TenantRecordActivityServiceTests.FavoriteUsesCanonicalRecordIdentity
192. BuildWithHQ.TenantRuntime.Tests.TenantRecordActivityServiceTests.InvalidBoundsFailBeforeDatabase
193. BuildWithHQ.TenantRuntime.Tests.TenantRecordActivityServiceTests.SearchAndActivityUseOnlyServerScope
194. BuildWithHQ.TenantRuntime.Tests.TenantRecordGraphLiveDatabaseTests.LiveGoldenRecordGraphRejectsReadOnlyMutation
195. BuildWithHQ.TenantRuntime.Tests.TenantRecordGraphLiveDatabaseTests.LiveGoldenRecordGraphRejectsWrongSaas
196. BuildWithHQ.TenantRuntime.Tests.TenantRecordGraphLiveDatabaseTests.LiveGoldenRecordGraphSecuresTraversalMetadataAndMutations
197. BuildWithHQ.TenantRuntime.Tests.TenantRecordGraphServiceTests.ControllerAndMigrationKeepGraphAuthorizationBoundaries
198. BuildWithHQ.TenantRuntime.Tests.TenantRecordGraphServiceTests.FactoryRejectsHostTokenMismatch
199. BuildWithHQ.TenantRuntime.Tests.TenantRecordGraphServiceTests.InvalidBoundsFailBeforeDatabase
200. BuildWithHQ.TenantRuntime.Tests.TenantRecordGraphServiceTests.MutationsUseRecordAndRelationTargets
201. BuildWithHQ.TenantRuntime.Tests.TenantRecordGraphServiceTests.RelatedKnowledgeUsesIndependentScopeAiFenceAndBounds
202. BuildWithHQ.TenantRuntime.Tests.TenantRecordGraphServiceTests.SearchAndGraphUseOnlyServerScope
203. BuildWithHQ.TenantRuntime.Tests.TenantReservationsServiceTests.ControllerAndMigrationKeepTheProcedureOnlyBoundary
204. BuildWithHQ.TenantRuntime.Tests.TenantReservationsServiceTests.InvalidInputsFailBeforeDatabaseAccess
205. BuildWithHQ.TenantRuntime.Tests.TenantReservationsServiceTests.PurchaseUsesServerIdentityAndIdempotentChargeContract
206. BuildWithHQ.TenantRuntime.Tests.TenantUniversalInboxControllerTests.BadgeEndpointReturnsTypedPayloadAndDisablesCaching
207. BuildWithHQ.TenantRuntime.Tests.TenantUniversalInboxControllerTests.EndpointsAreAuthenticatedAndHaveNoCallerIdentityFields
208. BuildWithHQ.TenantRuntime.Tests.TenantUniversalInboxControllerTests.HostAndTokenMismatchFailsBeforeTenantDatabaseRouting
209. BuildWithHQ.TenantRuntime.Tests.TenantUniversalInboxControllerTests.HumanStateEndpointUsesRouteIdentityAndReturnsNoContent
210. BuildWithHQ.TenantRuntime.Tests.TenantWebLinksLiveDatabaseTests.LiveGoldenWebLinksRejectsCreateWithoutCanCreateAndLeavesNoRecord
211. BuildWithHQ.TenantRuntime.Tests.TenantWebLinksLiveDatabaseTests.LiveGoldenWebLinksRespectsSaasRoleLocationAndUniversalRecords
212. BuildWithHQ.TenantRuntime.Tests.TenantWebLinksServiceTests.ControllerAndMigrationKeepScopeOnServerAndUseUniversalFeatures
213. BuildWithHQ.TenantRuntime.Tests.TenantWebLinksServiceTests.CreateAndUpdateUseSafeUrlsTypedFieldsAndConcurrencyFence
214. BuildWithHQ.TenantRuntime.Tests.TenantWebLinksServiceTests.FactoryRejectsHostTokenMismatchBeforeTenantRouting
215. BuildWithHQ.TenantRuntime.Tests.TenantWebLinksServiceTests.FavoriteUsesUniversalRecordIdentityAndServerScope
216. BuildWithHQ.TenantRuntime.Tests.TenantWebLinksServiceTests.ListUsesOnlyServerDerivedScopeAndParsesUniversalRecords
217. BuildWithHQ.TenantRuntime.Tests.TenantWebLinksServiceTests.UnsafeUrlsFailBeforeDatabaseWithRequestCorrelation
218. BuildWithHQ.TenantRuntime.Tests.TenantWorkOrdersLiveDatabaseTests.LiveGoldenWorkOrdersRespectLifecycleAssignmentAndSecurityContracts
219. BuildWithHQ.TenantRuntime.Tests.TenantWorkOrdersServiceTests.AssignmentPreservesConcurrencyAndServerScope
220. BuildWithHQ.TenantRuntime.Tests.TenantWorkOrdersServiceTests.ControllerAndMigrationEnforceFirstClassSecurityContract
221. BuildWithHQ.TenantRuntime.Tests.TenantWorkOrdersServiceTests.InvalidLifecycleInputsFailBeforeDatabaseAccess
222. BuildWithHQ.TenantRuntime.Tests.TenantWorkOrdersServiceTests.ListUsesOnlyReviewedServerScopedContract
223. BuildWithHQ.TenantRuntime.Tests.TenantWorkflowApprovalsControllerTests.EndpointIsAuthenticatedAndExposesNoCallerIdentityParameters
224. BuildWithHQ.TenantRuntime.Tests.TenantWorkflowApprovalsControllerTests.EndpointRoutesOnlyInboxFenceDecisionAndReason
225. BuildWithHQ.TenantRuntime.Tests.TenantWorkflowApprovalsControllerTests.PermissionFailureMapsToForbiddenWithoutLeakingDetails

**Universal Inbox and Support Tickets — 43 passed**
1. BuildWithHQ.UniversalInbox.Tests.ConversationChannelAdapterTests.InvalidOrUnstableEventFailsBeforeDatabaseExecution
2. BuildWithHQ.UniversalInbox.Tests.ConversationChannelAdapterTests.StableProviderIdentityAndServerTenantScopeReachCanonicalIngest
3. BuildWithHQ.UniversalInbox.Tests.ConversationChannelAdapterTests.TenantUserCannotCrossTrustedWebChatBoundary
4. BuildWithHQ.UniversalInbox.Tests.ExternalEventInboxAdapterTests.NullEventFailsBeforeCallingWriter
5. BuildWithHQ.UniversalInbox.Tests.ExternalEventInboxAdapterTests.PublishMapsStableExternalIdentityAndCanonicalSource
6. BuildWithHQ.UniversalInbox.Tests.ExternalEventInboxAdapterTests.RetryKeepsTheSameDedupeAnchor
7. BuildWithHQ.UniversalInbox.Tests.InboxRoutingPolicyContractTests.DeploymentMigrationContainsValidatorEvaluatorFenceAndAudit
8. BuildWithHQ.UniversalInbox.Tests.InboxRoutingPolicyContractTests.VersionOneSchemasAreClosedBoundedAndMatchSqlPolicyKeys
9. BuildWithHQ.UniversalInbox.Tests.InboxRoutingServiceTests.InvalidTargetAndEventFailBeforeDatabaseExecution
10. BuildWithHQ.UniversalInbox.Tests.InboxRoutingServiceTests.TenantUserCannotInvokeTrustedRoutingBoundary
11. BuildWithHQ.UniversalInbox.Tests.InboxRoutingServiceTests.TrustedServiceUsesServerAccountScopeAndBoundedEvent
12. BuildWithHQ.UniversalInbox.Tests.UniversalInboxLiveDatabaseTests.LiveGoldenGoClawInboxLifecycleIsIsolated
13. BuildWithHQ.UniversalInbox.Tests.UniversalInboxLiveDatabaseTests.LiveGoldenInboxSecurityRoutingAndFreshnessAreIsolated
14. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.BadgeIncludesUnreadApprovalHumanAndGoClawWorkingCounts
15. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.BadgeNormalizesSqlOmittedZeroAggregates
16. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.DeliveryDebugUsesServerScopeAndParsesSafeRetryState
17. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.DetailRejectsIdentityThatDoesNotMatchServerScope
18. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.DetailReturnsSourcePointerWithoutReplacingSourceDocument
19. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.IngestionWithoutStableDedupeAnchorFailsBeforeDatabaseExecution
20. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.InvalidNotificationLimitFailsBeforeDatabaseExecution
21. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.InvalidStatusFailsBeforeDatabaseExecution
22. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.NotificationsUseSecuredScopeAndInboxItemIdentity
23. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.QueueFailsClosedWhenProcedureShapeDrifts
24. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.QueueUsesOnlyServerDerivedScopeAndParsesTypedItems
25. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.ReadAndStatusMutationsUseVerifiedUserIdentity
26. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.TenantUserCannotInvokeTrustedIngestionBoundary
27. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.TicketingSettingsUseVerifiedScopeAndNormalizePrefix
28. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.TrustedIngestionPassesStableDedupeKeyAndServerAppAccount
29. BuildWithHQ.UniversalInbox.Tests.UniversalInboxServiceTests.UnrevalidatedTenantScopeFailsBeforeDatabaseExecution
30. BuildWithHQ.UniversalInbox.Tests.UniversalInboxSqlContractTests.BadgeAndNotificationsCountOnlySecuredInboxItems
31. BuildWithHQ.UniversalInbox.Tests.UniversalInboxSqlContractTests.CreateOrTouchIsConcurrencySafeAndDatabaseUnique
32. BuildWithHQ.UniversalInbox.Tests.UniversalInboxSqlContractTests.CurrentRecordSecurityAggregatesMultipleRoleEntitlements
33. BuildWithHQ.UniversalInbox.Tests.UniversalInboxSqlContractTests.CurrentSuggestionBatchPointerUsesTheFullNullableScopeFence
34. BuildWithHQ.UniversalInbox.Tests.UniversalInboxSqlContractTests.DeliveryOperationsUseRecordEnvelopeEditPermissionAndLeaseFence
35. BuildWithHQ.UniversalInbox.Tests.UniversalInboxSqlContractTests.DirectAndWebChatAdaptersKeepCanonicalDedupeAndParticipantSecurity
36. BuildWithHQ.UniversalInbox.Tests.UniversalInboxSqlContractTests.EmptyRoutingAuditJsonMigrationIsTargetGuardedAndIdempotent
37. BuildWithHQ.UniversalInbox.Tests.UniversalInboxSqlContractTests.GoClawLifecycleFixtureRequiresHumanDecisionAndPreservesLineage
38. BuildWithHQ.UniversalInbox.Tests.UniversalInboxSqlContractTests.HumanInboxOperationsReapplyCurrentRecordSecurity
39. BuildWithHQ.UniversalInbox.Tests.UniversalInboxSqlContractTests.InboundEmailAndSmsEnterGoClawOnlyThroughUniversalInbox
40. BuildWithHQ.UniversalInbox.Tests.UniversalInboxSqlContractTests.InboxRemainsPointerWhileConversationStaysCanonical
41. BuildWithHQ.UniversalInbox.Tests.UniversalInboxSqlContractTests.IntegrationContractsKeepSlaRoutingAndStaleWorkOnThePointer
42. BuildWithHQ.UniversalInbox.Tests.UniversalInboxSqlContractTests.RichRoutingIsDeterministicScopedFencedAndAudited
43. BuildWithHQ.UniversalInbox.Tests.UniversalInboxSqlContractTests.RoutingRuleActivationValidatesVersionedJsonBeforeWrite

**AI and secured retrieval — 162 passed**
1. BuildWithHQ.Ai.Tests.AiAnswerEndpointClientTests.HttpFailureOrMalformedEnvelopeFailsWithoutLeakingBody
2. BuildWithHQ.Ai.Tests.AiAnswerEndpointClientTests.SendsDeterministicJsonModeRequestAndParsesOneChoice
3. BuildWithHQ.Ai.Tests.AiApiRuntimeContextTests.RejectsDeniedCrossTenantAndCorrelationMismatchedContracts
4. BuildWithHQ.Ai.Tests.AiApiRuntimeContextTests.ResolvesOnlyTheAuthenticatedRuntimePrincipalAndSearchScope
5. BuildWithHQ.Ai.Tests.AiApiRuntimeContextTests.StatusAndEmptySearchDoNotCallEmbeddingOrRetrievalDependencies
6. BuildWithHQ.Ai.Tests.AiApiSqlContractTests.MigrationAndCurrentExportPreserveTheServerDerivedAiBoundary
7. BuildWithHQ.Ai.Tests.AiArchiveDeleteSynchronizationLiveDatabaseTests.LiveGoldenRetirementArchivesVectorsAndRemovesEvidence
8. BuildWithHQ.Ai.Tests.AiArchiveDeleteSynchronizationSqlContractTests.MigrationArchivesCanonicalVectorsAndRemovesRetrievalEvidence
9. BuildWithHQ.Ai.Tests.AiArchiveDeleteSynchronizationSqlContractTests.WorkerPurgesArtifactsOnlyAfterReviewedDatabaseReceipt
10. BuildWithHQ.Ai.Tests.AiChunkingLiveDatabaseTests.LiveGoldenChunkingIsStableAtomicCitedAndRolledBack
11. BuildWithHQ.Ai.Tests.AiChunkingSqlContractTests.MigrationReusesCanonicalChunksWithVersionAndCitationFences
12. BuildWithHQ.Ai.Tests.AiChunkingSqlContractTests.WorkerUsesReviewedContractsAndDoesNotSendTextToAnEmbeddingClient
13. BuildWithHQ.Ai.Tests.AiEmbedding1024LiveDatabaseTests.LiveGoldenEmbedding1024IsScopedNormalizedVisualAndRestartSafe
14. BuildWithHQ.Ai.Tests.AiEmbedding1024SqlContractTests.MigrationSecuresChunkAndExistingVisual1024Lanes
15. BuildWithHQ.Ai.Tests.AiEmbedding1024SqlContractTests.WorkerUsesReviewedDimensionSpecificContracts
16. BuildWithHQ.Ai.Tests.AiEmbedding1998SqlContractTests.CurrentSchemaAndWorkerUseExact1998Lane
17. BuildWithHQ.Ai.Tests.AiEmbedding1998SqlContractTests.MigrationKeeps1998StorageAndSecuresPreparationAndStore
18. BuildWithHQ.Ai.Tests.AiEmbedding256LiveDatabaseTests.LiveGoldenEmbedding256IsScopedNormalizedAndRestartSafe
19. BuildWithHQ.Ai.Tests.AiEmbedding256SqlContractTests.OrchestrationProfileDoesNotBindUnverifiedWorkers
20. BuildWithHQ.Ai.Tests.AiEmbedding256SqlContractTests.TenantMigrationUsesCanonicalTablesAndStrictVectorFences
21. BuildWithHQ.Ai.Tests.AiEmbedding256SqlContractTests.WorkerAcceptsOnlyScopedNormalized256DJobs
22. BuildWithHQ.Ai.Tests.AiEndpointRoutingLiveDatabaseTests.LiveGoldenEndpointRegistryIsIdempotentHealthyAndCapabilityRouted
23. BuildWithHQ.Ai.Tests.AiEndpointRoutingSqlContractTests.MigrationRegistersAndRoutesOnlyFreshCapabilityModelMatches
24. BuildWithHQ.Ai.Tests.AiGroundedAnswerServiceTests.AiReadDenialStopsBeforeContextOrEndpoint
25. BuildWithHQ.Ai.Tests.AiGroundedAnswerServiceTests.AuthorizationChangeDuringHarnessResolutionStopsBeforeRouting
26. BuildWithHQ.Ai.Tests.AiGroundedAnswerServiceTests.AuthorizationChangeDuringModelCallRejectsAnswer
27. BuildWithHQ.Ai.Tests.AiGroundedAnswerServiceTests.EmptyContextReturnsSafeAnswerWithoutCallingModel
28. BuildWithHQ.Ai.Tests.AiGroundedAnswerServiceTests.GeneratesGroundedAnswerAndServerBuiltRecordLink
29. BuildWithHQ.Ai.Tests.AiGroundedAnswerServiceTests.HallucinatedDuplicateOrMissingCitationsFailClosed
30. BuildWithHQ.Ai.Tests.AiGroundedAnswerServiceTests.PublicAnswerApisAcceptNoCallerIdentityContextOrLinks
31. BuildWithHQ.Ai.Tests.AiGroundedAnswerServiceTests.SuccessfulAnswerFailsClosedWhenEvidenceAppendFails
32. BuildWithHQ.Ai.Tests.AiGroundedAnswerServiceTests.TenantHarnessOverrideChangesProductionPromptAndGenerationProfile
33. BuildWithHQ.Ai.Tests.AiGroundedAnswerServiceTests.TenantHarnessOverrideObservablyChangesProductionAnswerStyle
34. BuildWithHQ.Ai.Tests.AiGroundedAnswerServiceTests.TwoStageGenerationUsesTwoStageContextPath
35. BuildWithHQ.Ai.Tests.AiGroundedAnswerServiceTests.UnsafeOrUnapprovedEndpointStopsBeforeEvidenceLeavesService
36. BuildWithHQ.Ai.Tests.AiHarnessContextTests.CurrentSqlAndProductionPathRetainSecuredFourLayerPrecedence
37. BuildWithHQ.Ai.Tests.AiHarnessContextTests.GoldenPromptIsByteExactAndEmptyHarnessPreservesBaseline
38. BuildWithHQ.Ai.Tests.AiHarnessContextTests.ResolverDerivesScopeAndConsumesRankedFourLayerContract
39. BuildWithHQ.Ai.Tests.AiLiveQueryEmbeddingServiceTests.AiReadDenialStopsBeforeRoutingOrEndpointUse
40. BuildWithHQ.Ai.Tests.AiLiveQueryEmbeddingServiceTests.InvalidEndpointVectorsFailClosed
41. BuildWithHQ.Ai.Tests.AiLiveQueryEmbeddingServiceTests.NativeVectorUsesExactRoutingProfileAndNormalizesEveryStorageLane
42. BuildWithHQ.Ai.Tests.AiLiveQueryEmbeddingServiceTests.OpenAiAdapterSendsIndexedTextProfileAndParsesOneStrictVector
43. BuildWithHQ.Ai.Tests.AiLiveQueryEmbeddingServiceTests.PublicQueryApiAcceptsNoCallerTenantAuthorizationOrEvidenceScope
44. BuildWithHQ.Ai.Tests.AiLiveQueryEmbeddingServiceTests.RequestedSizeVectorMustAlreadyBeNormalizedAndIsNotRenormalized
45. BuildWithHQ.Ai.Tests.AiLiveQueryEmbeddingServiceTests.UnsafeOrUncorrelatedRoutingStopsBeforeEndpointUse
46. BuildWithHQ.Ai.Tests.AiLiveQueryEmbeddingServiceTests.WrongModelResponseFailsClosed
47. BuildWithHQ.Ai.Tests.AiModelContextAuthorizationTests.AggregateAiDenialStopsBeforeDataLoadOrPromptConstruction
48. BuildWithHQ.Ai.Tests.AiModelContextAuthorizationTests.BuildsContextFromNormallyAndAiReadableRecords
49. BuildWithHQ.Ai.Tests.AiModelContextAuthorizationTests.CrossTenantSourceResultFailsBeforePromptConstruction
50. BuildWithHQ.Ai.Tests.AiModelContextAuthorizationTests.ForwardedAiSnapshotCannotAuthorizeModelContext
51. BuildWithHQ.Ai.Tests.AiModelContextAuthorizationTests.NormalReadPermissionDoesNotSubstituteForAiReadGrant
52. BuildWithHQ.Ai.Tests.AiModelContextAuthorizationTests.OrdinaryReadableButAiExcludedRecordNeverReachesRenderer
53. BuildWithHQ.Ai.Tests.AiModelContextAuthorizationTests.PublicContextApisAcceptNoCallerTenantScope
54. BuildWithHQ.Ai.Tests.AiModelContextAuthorizationTests.UnrequestedSourceRecordFailsBeforePromptConstruction
55. BuildWithHQ.Ai.Tests.AiMrlNormalizationContractTests.NativeFallbackMatchesSharedCrossRuntimeGoldenForEveryLane
56. BuildWithHQ.Ai.Tests.AiMrlNormalizationContractTests.RequestedSizeNonNormalizedOutputFailsInsteadOfBeingFixed
57. BuildWithHQ.Ai.Tests.AiMrlNormalizationContractTests.RequestedSizeOutputIsValidatedAndPreservedForEveryLane
58. BuildWithHQ.Ai.Tests.AiMultimodalRagEndToEndTests.AiReadDenialStopsEntireComposedPathBeforeVisualOrRouting
59. BuildWithHQ.Ai.Tests.AiMultimodalRagEndToEndTests.AuthorizedChartFlowsThroughRerankContextAnswerAndAuditWithExactCitation
60. BuildWithHQ.Ai.Tests.AiMultimodalRerankerServiceTests.AiReadDenialStopsBeforeRetrievalVisualRoutingOrModel
61. BuildWithHQ.Ai.Tests.AiMultimodalRerankerServiceTests.AuthorizationChangeOrInvalidScoreResponseFailsClosed
62. BuildWithHQ.Ai.Tests.AiMultimodalRerankerServiceTests.AuthorizedMixedEvidencePreservesCitationsAndSupportsConfigured8BProfile
63. BuildWithHQ.Ai.Tests.AiMultimodalRerankerServiceTests.CrossTenantOrMismatchedVisualEvidenceNeverReachesModel
64. BuildWithHQ.Ai.Tests.AiMultimodalRerankerServiceTests.PublicApiAcceptsNoCallerIdentityCandidateOrEvidenceScope
65. BuildWithHQ.Ai.Tests.AiMultimodalRerankerServiceTests.VllmAdapterSendsAuthorizedBytesAsDataUrlWithoutStorageAddress
66. BuildWithHQ.Ai.Tests.AiMultimodalRerankerSqlContractTests.CurrentResolverRequiresCapabilityHealthLaneAndExactModel
67. BuildWithHQ.Ai.Tests.AiMultimodalRerankerSqlContractTests.MigrationRegistersDefaultWithoutBindingAContainerOrWorker
68. BuildWithHQ.Ai.Tests.AiOperationsDashboardServiceTests.AuthorizedOperatorReceivesBoundedOperationalSnapshot
69. BuildWithHQ.Ai.Tests.AiOperationsDashboardServiceTests.InvalidWindowAndMalformedDatabaseShapeFailClosed
70. BuildWithHQ.Ai.Tests.AiOperationsDashboardServiceTests.PublicApiAcceptsNoTenantOrDatabaseIdentity
71. BuildWithHQ.Ai.Tests.AiOperationsDashboardServiceTests.UnauthorizedIdentityStopsBeforeDatabase
72. BuildWithHQ.Ai.Tests.AiOperationsDashboardSqlContractTests.DashboardReadersReturnOnlyAggregatedOperationalState
73. BuildWithHQ.Ai.Tests.AiOperationsJobServiceTests.AuthorizationAndInputValidationStopBeforeDatabase
74. BuildWithHQ.Ai.Tests.AiOperationsJobServiceTests.MalformedDatabaseIdentityFailsClosed
75. BuildWithHQ.Ai.Tests.AiOperationsJobServiceTests.OperatorCanListBoundedRedactedJobs
76. BuildWithHQ.Ai.Tests.AiOperationsJobServiceTests.RetryUsesExactObservedFenceAndServerCorrelation
77. BuildWithHQ.Ai.Tests.AiOperationsJobSqlContractTests.MigrationPreservesFencesRedactionAndLeastPrivilege
78. BuildWithHQ.Ai.Tests.AiQueryEvidenceLiveDatabaseTests.LiveGoldenEvidenceAppendIsCompleteIdempotentHashedAndRolledBack
79. BuildWithHQ.Ai.Tests.AiQueryEvidenceLoggerTests.AppendTargetsLogsPlaneAndSerializesScopeRouteCitationsAndTokens
80. BuildWithHQ.Ai.Tests.AiQueryEvidenceLoggerTests.AuthorizationChangeStopsBeforeLogsPlane
81. BuildWithHQ.Ai.Tests.AiQueryEvidenceLoggerTests.EvidenceConstructionIsNotCallerAccessible
82. BuildWithHQ.Ai.Tests.AiQueryEvidenceLoggerTests.MissingLogIdFailsClosed
83. BuildWithHQ.Ai.Tests.AiQueryEvidenceSqlContractTests.CurrentLogsExportContainsTheCanonicalEvidenceContract
84. BuildWithHQ.Ai.Tests.AiQueryEvidenceSqlContractTests.LoggerUsesOnlyTheGeneratedLogsPlaneProcedureContract
85. BuildWithHQ.Ai.Tests.AiRagContextBuilderTests.AiReadDenialStopsBeforeRetrieval
86. BuildWithHQ.Ai.Tests.AiRagContextBuilderTests.BuildsDeterministicBoundedEnvelopeWithSecurityAndFullCitation
87. BuildWithHQ.Ai.Tests.AiRagContextBuilderTests.ChangedAuthorizationSnapshotStopsAfterRetrieval
88. BuildWithHQ.Ai.Tests.AiRagContextBuilderTests.CrossTenantCandidateFailsAtFinalPromptBoundary
89. BuildWithHQ.Ai.Tests.AiRagContextBuilderTests.ExcessVisualCitationSetFailsClosed
90. BuildWithHQ.Ai.Tests.AiRagContextBuilderTests.HardContextLimitDropsOnlyWholeTrailingEvidenceItems
91. BuildWithHQ.Ai.Tests.AiRagContextBuilderTests.LongChunkIsSafelyTruncatedWithoutDroppingCitation
92. BuildWithHQ.Ai.Tests.AiRagContextBuilderTests.PublicRagApisAcceptNoCallerIdentityScopeOrRawCandidates
93. BuildWithHQ.Ai.Tests.AiRagContextBuilderTests.TwoStageContextUsesFixedAuthorizedPoolAndPreservesBothScores
94. BuildWithHQ.Ai.Tests.AiRebuildOperationsServiceTests.InvalidSourceShapeStopsBeforeDatabaseCall
95. BuildWithHQ.Ai.Tests.AiRebuildOperationsServiceTests.NonOwnerCannotQueueOrReadRebuilds
96. BuildWithHQ.Ai.Tests.AiRebuildOperationsServiceTests.OwnerQueuesSourceReembedFromTrustedScope
97. BuildWithHQ.Ai.Tests.AiRebuildOperationsServiceTests.PublicApiAcceptsNoCallerAuthorizationOrModelIdentity
98. BuildWithHQ.Ai.Tests.AiRebuildOperationsServiceTests.StatusIsReadOnlyWithinTrustedTenant
99. BuildWithHQ.Ai.Tests.AiRebuildOperationsSqlContractTests.RebuildMigrationUsesCanonicalEvidenceAndDurableHistoricalDedupe
100. BuildWithHQ.Ai.Tests.AiRebuildOperationsSqlContractTests.WorkerUsesReviewedLeaseProceduresWithoutAdHocDml
101. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrieval1998SqlContractTests.CurrentExportAndServiceExposeTheReviewed1998Contract
102. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrieval1998SqlContractTests.Legacy1998ProcedureRemainsNamedBecauseTheLoggedSearchCallsIt
103. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrieval1998SqlContractTests.MigrationUsesOnlyCanonicalStrict1998RetrievalGraph
104. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrievalLiveDatabaseTests.LiveGolden1998CandidateRetrievalIsFailClosedReadOnlyAndCitationStable
105. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrievalLiveDatabaseTests.LiveGoldenCandidateRetrievalIsFailClosedReadOnlyAndCitationStable
106. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrievalServiceTests.AiReadDenialStopsBeforeScopeOrDatabase
107. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrievalServiceTests.AuthorizedCandidatePreservesStableTextElementAndVisualCitation
108. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrievalServiceTests.CrossTenantScopeStopsBeforeDatabase
109. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrievalServiceTests.HighResolutionPathRejectsWrongProfileOrAiDenialBeforeScopeAndDatabase
110. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrievalServiceTests.HighResolutionPathUsesExact1998ProfileAndPreservesCitation
111. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrievalServiceTests.MalformedOrDuplicatedCitationEvidenceFailsClosed
112. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrievalServiceTests.PublicRetrievalApisAcceptNoCallerTenantOrAuthorizationScope
113. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrievalServiceTests.RetrievalRequiresCanonical1024QueryProfile
114. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrievalServiceTests.ScopeRejectsEmptyOrAmbiguousAuthorizationSets
115. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrievalServiceTests.WidenedDatabaseRowsFailClosedBeforeBecomingCandidates
116. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrievalSqlContractTests.MigrationFiltersBeforeVectorOrderingAndRevalidatesCitationGraph
117. BuildWithHQ.Ai.Tests.AiSecuredCandidateRetrievalSqlContractTests.ServiceCallsOnlyTheReviewedSecuredProcedure
118. BuildWithHQ.Ai.Tests.AiSourceChangeSchedulerLiveDatabaseTests.LiveGoldenChangeSchedulingIsDeterministicScopedAndRolledBack
119. BuildWithHQ.Ai.Tests.AiSourceChangeSchedulerServiceTests.AiReadDenialStopsBeforeScheduling
120. BuildWithHQ.Ai.Tests.AiSourceChangeSchedulerServiceTests.PublicSchedulerApiAcceptsNoCallerTenantOrAuthorizationScope
121. BuildWithHQ.Ai.Tests.AiSourceChangeSchedulerServiceTests.RejectsInvalidBatchSizeBeforeScheduling
122. BuildWithHQ.Ai.Tests.AiSourceChangeSchedulerServiceTests.SchedulesOnlyTheTrustedCurrentTenantAndReturnsCounts
123. BuildWithHQ.Ai.Tests.AiSourceChangeSchedulerSqlContractTests.MigrationUsesExistingCanonicalChainAndHistoricalVersionDedupe
124. BuildWithHQ.Ai.Tests.AiSourceChangeSchedulerSqlContractTests.ProductionWorkerCallsReviewedProceduresWithoutAdHocDml
125. BuildWithHQ.Ai.Tests.AiSourceRegistrationLiveDatabaseTests.LiveGoldenSourceRegistrationIsIdempotentSecuredAndRolledBack
126. BuildWithHQ.Ai.Tests.AiSourceRegistrationServiceTests.AggregateAiDenialStopsBeforeSourceLoadAndDatabaseCall
127. BuildWithHQ.Ai.Tests.AiSourceRegistrationServiceTests.ChangedAuthoritativeFingerprintProducesChangedHash
128. BuildWithHQ.Ai.Tests.AiSourceRegistrationServiceTests.CitationMetadataPreservesProviderPageAndStableSourceIdentity
129. BuildWithHQ.Ai.Tests.AiSourceRegistrationServiceTests.CrossTenantOrWidenedSourceStopsBeforeDatabaseRegistration
130. BuildWithHQ.Ai.Tests.AiSourceRegistrationServiceTests.PublicRegistrationApisAcceptNoCallerTenantOrAuthorizationScope
131. BuildWithHQ.Ai.Tests.AiSourceRegistrationServiceTests.RecordOrAiReadDenialStopsBeforeDatabaseRegistration
132. BuildWithHQ.Ai.Tests.AiSourceRegistrationServiceTests.RegistersEveryCanonicalSourceKindThroughExistingProcedure
133. BuildWithHQ.Ai.Tests.AiSourceRegistrationServiceTests.StableRetryKeepsHashSourceAndCitationIdentity
134. BuildWithHQ.Ai.Tests.AiSourceRegistrationSqlContractTests.CurrentAiSchemaKeepsCanonicalMultimodalChainAndVectorDimensions
135. BuildWithHQ.Ai.Tests.AiSourceRegistrationSqlContractTests.MigrationUsesCanonicalBridgeAndSerializedNaturalIdentity
136. BuildWithHQ.Ai.Tests.AiTwoStageCandidateRetrievalLiveDatabaseTests.LiveGoldenTwoStageRetrievalSecuresBeforeTopAndPrecisionOrders
137. BuildWithHQ.Ai.Tests.AiTwoStageCandidateRetrievalServiceTests.AiReadDenialStopsTwoStageBeforeScopeAndDatabase
138. BuildWithHQ.Ai.Tests.AiTwoStageCandidateRetrievalServiceTests.AuthorizedTwoStageRetrievalUsesCurrentScopeAndPreservesBothScores
139. BuildWithHQ.Ai.Tests.AiTwoStageCandidateRetrievalServiceTests.KnowledgeAwareRetrievalCarriesExactRevisionAndSecuredPreferences
140. BuildWithHQ.Ai.Tests.AiTwoStageCandidateRetrievalServiceTests.PublicTwoStageApiAcceptsNoCallerTenantOrAuthorizationPolicy
141. BuildWithHQ.Ai.Tests.AiTwoStageCandidateRetrievalServiceTests.TwoStageDatabaseRowsAreRevalidatedAgainstCurrentScope
142. BuildWithHQ.Ai.Tests.AiTwoStageCandidateRetrievalServiceTests.TwoStageRejectsWrongVectorPairOrCandidateBoundsBeforeAuthorization
143. BuildWithHQ.Ai.Tests.AiTwoStageCandidateRetrievalSqlContractTests.MigrationSecuresStageOneBeforeTopAndPolicyGatesPrecisionOrdering
144. BuildWithHQ.Ai.Tests.AiTwoStageCandidateRetrievalSqlContractTests.ServiceUsesReviewedTwoStageProcedureWithoutCallerScopeOrAdHocSql
145. BuildWithHQ.Ai.Tests.CrmRecordCandidateSourceTests.CurrentAiDenialStopsBeforeDatabaseCall
146. BuildWithHQ.Ai.Tests.CrmRecordCandidateSourceTests.LoadsSanitizedRecordUsingOnlyCurrentServerScope
147. BuildWithHQ.Ai.Tests.CrmRecordCandidateSourceTests.RejectsCrossTenantDeniedOrMalformedDatabaseContracts
148. BuildWithHQ.Ai.Tests.CrmRecordCandidateSourceTests.RejectsNonRecordOrAliasedPrimaryIdentityBeforeDatabaseCall
149. BuildWithHQ.Ai.Tests.CrmRecordExtractionSqlContractTests.CurrentProcedureSecuresRecordBeforeProjectingFields
150. BuildWithHQ.Ai.Tests.CrmRecordExtractionSqlContractTests.MigrationIsAnIdempotentProcedureOnlyChange
151. BuildWithHQ.Ai.Tests.DataChatLiveDatabaseTests.LiveGoldenDataChatUsesCustomFieldsGlossaryAndRevalidatesStoredRecordIds
152. BuildWithHQ.Ai.Tests.DataChatServiceTests.AiReadDenialStopsBeforeSessionOrPlanner
153. BuildWithHQ.Ai.Tests.DataChatServiceTests.ExistingSessionPassesOnlyLiveRevalidatedRecordIdsToPlanner
154. BuildWithHQ.Ai.Tests.DataChatServiceTests.GlossaryConfirmationValidatesThroughFixedSqlBeforePersistingCurrentContract
155. BuildWithHQ.Ai.Tests.DataChatServiceTests.PlannerRejectsUnknownCustomFieldInsteadOfWideningQuery
156. BuildWithHQ.Ai.Tests.DataChatServiceTests.PublicRequestCannotSupplyTenantOrDatabaseIdentity
157. BuildWithHQ.Ai.Tests.DataChatServiceTests.StructuredSemanticAndBlendedRoutesPersistCurrentEvidence
158. BuildWithHQ.Ai.Tests.DataChatSqlContractTests.CanonicalServiceUsesCurrentChatAndSecuredRagContracts
159. BuildWithHQ.Ai.Tests.DataChatSqlContractTests.MigrationUsesFixedSqlCurrentContractsAndFullSecurityEnvelope
160. BuildWithHQ.Ai.Tests.StoredProcedureDataChatStoreTests.GlossaryConfirmationUsesCurrentContractAndServerDerivedUser
161. BuildWithHQ.Ai.Tests.StoredProcedureDataChatStoreTests.SessionLoadRedactsAnswerAndRemovesRevokedRecordIds
162. BuildWithHQ.Ai.Tests.StoredProcedureDataChatStoreTests.StructuredExecutionUsesOnlyServerScopeAndReviewedPlanJson

**Workflows and governed actions — 34 passed**
1. BuildWithHQ.Workflow.Tests.ActionCancelUndoLiveDatabaseTests.CancelAndUndoAreSecuredFencedIdempotentAndRollbackOnly
2. BuildWithHQ.Workflow.Tests.ActionControlServiceTests.CancellationNormalizesReasonAndRequiresTerminalResult
3. BuildWithHQ.Workflow.Tests.ActionControlServiceTests.CapabilityLineageMismatchFailsClosed
4. BuildWithHQ.Workflow.Tests.ActionControlServiceTests.MissingCurrentAiReadScopeFailsBeforeDatabase
5. BuildWithHQ.Workflow.Tests.ActionControlServiceTests.UndoRequestUsesVerifiedServerIdentityAndStableRequestId
6. BuildWithHQ.Workflow.Tests.ActionControlSqlContractTests.MigrationGatesCapabilitiesAndUsesFencedDurableUndo
7. BuildWithHQ.Workflow.Tests.FormWorkflowBindingLiveDatabaseTests.FormDispatchIsRestartSafeAuthorizedAuditedAndRollbackOnly
8. BuildWithHQ.Workflow.Tests.FormWorkflowBindingServiceTests.MissingPermissionAndDynamicDispatchTextFailBeforeDatabase
9. BuildWithHQ.Workflow.Tests.FormWorkflowBindingServiceTests.UpsertUsesOnlyVerifiedIdentityAndStableBindingTargets
10. BuildWithHQ.Workflow.Tests.FormWorkflowBindingSqlContractTests.MigrationUsesServerBindingsDurableReceiptsAndAtomicWorkflowStart
11. BuildWithHQ.Workflow.Tests.WorkflowApprovalServiceTests.DecisionUsesOnlyInboxFenceAndVerifiedServerIdentity
12. BuildWithHQ.Workflow.Tests.WorkflowApprovalServiceTests.InvalidDecisionAndFenceFailBeforeDatabase
13. BuildWithHQ.Workflow.Tests.WorkflowApprovalServiceTests.MismatchedDecisionResultFailsClosed
14. BuildWithHQ.Workflow.Tests.WorkflowApprovalServiceTests.MissingPermissionAndForwardedIdentityFailBeforeDatabase
15. BuildWithHQ.Workflow.Tests.WorkflowApprovalSqlContractTests.MigrationUsesLeaseFencedParkingAndSecuredVersionedDecisions
16. BuildWithHQ.Workflow.Tests.WorkflowBranchConditionLiveDatabaseTests.BranchResolutionAndCompletionAreAuthorizedFencedAndRollbackOnly
17. BuildWithHQ.Workflow.Tests.WorkflowBranchConditionSqlContractTests.MigrationDerivesDurableBranchTransitionsFromFrozenConfiguration
18. BuildWithHQ.Workflow.Tests.WorkflowDesignerServiceTests.CreateUsesOnlyServerIdentityAndReturnsTypedGraph
19. BuildWithHQ.Workflow.Tests.WorkflowDesignerServiceTests.ForwardedOrUnverifiedSecurityCannotAuthorizeDesigner
20. BuildWithHQ.Workflow.Tests.WorkflowDesignerServiceTests.InvalidDatabaseShapeIsReturnedAsSafeContractFailure
21. BuildWithHQ.Workflow.Tests.WorkflowDesignerServiceTests.InvalidGraphFailsBeforeDatabaseExecution
22. BuildWithHQ.Workflow.Tests.WorkflowDesignerServiceTests.ManagePermissionAloneCannotPublish
23. BuildWithHQ.Workflow.Tests.WorkflowDesignerServiceTests.PublishCarriesRevisionFenceAndCurrentIdentity
24. BuildWithHQ.Workflow.Tests.WorkflowDesignerServiceTests.UserWithoutManagePermissionCannotReadOrMutate
25. BuildWithHQ.Workflow.Tests.WorkflowHumanApprovalLiveDatabaseTests.WorkflowApprovalsAreDurableSecuredAndAudited
26. BuildWithHQ.Workflow.Tests.WorkflowInternalServiceLiveDatabaseTests.CanonicalServiceStepPersistsAndInventedVariantIsRejected
27. BuildWithHQ.Workflow.Tests.WorkflowInternalServiceSqlContractTests.MigrationAddsOnlyTheCanonicalServiceStepToBothDatabaseValidators
28. BuildWithHQ.Workflow.Tests.WorkflowRemoteApiLiveDatabaseTests.ConnectorResolutionIsScopedAuthorizedAuditedAndRollbackOnly
29. BuildWithHQ.Workflow.Tests.WorkflowRemoteApiSqlContractTests.MigrationKeepsRemoteRoutingSecretsAndAuthorizationOnServer
30. BuildWithHQ.Workflow.Tests.WorkflowRunRequestServiceTests.DurableReplayReturnsOriginalRunAndInitialCorrelation
31. BuildWithHQ.Workflow.Tests.WorkflowRunRequestServiceTests.EmptyKeysAndMismatchedDatabaseLineageFailClosed
32. BuildWithHQ.Workflow.Tests.WorkflowRunRequestServiceTests.MissingPermissionOrUnverifiedIdentityFailsBeforeDatabase
33. BuildWithHQ.Workflow.Tests.WorkflowRunRequestServiceTests.StartUsesOpaqueRequestKeyAndOnlyVerifiedServerIdentity
34. BuildWithHQ.Workflow.Tests.WorkflowRunRequestSqlContractTests.MigrationUsesAccountScopedKeysAtomicSnapshotsAndServerAuthorization

**Knowledge Core — 12 passed**
1. BuildWithHQ.KnowledgeCore.Tests.KnowledgeCoreServiceTests.CollectionsAndOwnersUseTypedSecuredContracts
2. BuildWithHQ.KnowledgeCore.Tests.KnowledgeCoreServiceTests.CoreCrudUsesNamedJsonContractsAndOnlyServerScope
3. BuildWithHQ.KnowledgeCore.Tests.KnowledgeCoreServiceTests.InvalidInputFailsBeforeDatabase
4. BuildWithHQ.KnowledgeCore.Tests.KnowledgeCoreServiceTests.LifecycleAndRevisionOperationsCarryConcurrencyFences
5. BuildWithHQ.KnowledgeCore.Tests.KnowledgeCoreServiceTests.QuestionsFeedbackAndGapsUseTypedSecuredContracts
6. BuildWithHQ.KnowledgeCore.Tests.KnowledgeCoreServiceTests.ReviewsAndHealthUseTypedScopedContractsAndConcurrencyFences
7. BuildWithHQ.KnowledgeCore.Tests.KnowledgeCoreServiceTests.SqlContractsEnforceRecordScopeActionKeysAndNoDirectGrants
8. BuildWithHQ.KnowledgeCore.Tests.SupportLearningServiceTests.CreateCandidatePassesOnlySanitizedStructuredFieldsAndServerScope
9. BuildWithHQ.KnowledgeCore.Tests.SupportLearningServiceTests.InvalidOrUnsafeResponseFailsClosed
10. BuildWithHQ.KnowledgeCore.Tests.SupportLearningServiceTests.ListUsesSecuredTypedContract
11. BuildWithHQ.KnowledgeCore.Tests.SupportLearningServiceTests.SanitizerRemovesCredentialsPiiNetworkAndTenantIdentifiers
12. BuildWithHQ.KnowledgeCore.Tests.SupportLearningServiceTests.SqlContractRequiresResolvedSecuredSourceAndCreatesDraftReviewWork

**Integrations and connectors — 74 passed**
1. BuildWithHQ.Integrations.Tests.DeveloperApiCredentialTests.AuthenticatorAcceptsOnlyMatchingActiveStoredCredential
2. BuildWithHQ.Integrations.Tests.DeveloperApiCredentialTests.BuilderLifecycleRejectsNonBuilderBeforeSql
3. BuildWithHQ.Integrations.Tests.DeveloperApiCredentialTests.BuilderLifecycleUsesOnlyServerIdentityAndReturnsSecretOnce
4. BuildWithHQ.Integrations.Tests.DeveloperApiCredentialTests.GeneratedCredentialsAreStrictRandomAndRoundTrip
5. BuildWithHQ.Integrations.Tests.DeveloperApiCredentialTests.ScopeCatalogRejectsUnknownOrEmptyGrants
6. BuildWithHQ.Integrations.Tests.DeveloperApiCredentialTests.VersionedHmacProtectsAndRotatesWithoutPersistingRawSecret
7. BuildWithHQ.Integrations.Tests.DeveloperCapabilityAuthorizationTests.ForwardedSecuritySnapshotCannotAuthorizeEitherTransport
8. BuildWithHQ.Integrations.Tests.DeveloperCapabilityAuthorizationTests.MissingCredentialScopeDeniesBothTransports
9. BuildWithHQ.Integrations.Tests.DeveloperCapabilityAuthorizationTests.NamedPermissionDecisionIsSharedByBothTransports
10. BuildWithHQ.Integrations.Tests.DeveloperCapabilityAuthorizationTests.PublicTargetCannotSelectAccountOrPhysicalDatabase
11. BuildWithHQ.Integrations.Tests.DeveloperCapabilityAuthorizationTests.RestAndMcpAllowWithIdenticalDecisionFromTrustedContext
12. BuildWithHQ.Integrations.Tests.DeveloperCapabilityAuthorizationTests.RestAndMcpDenyCrossAppTargetWithoutRoutableIdentity
13. BuildWithHQ.Integrations.Tests.DeveloperConnectorRegistryTests.CrossAppTargetDeniesBothTransportsBeforeRegistryRead
14. BuildWithHQ.Integrations.Tests.DeveloperConnectorRegistryTests.DefaultRegistryIsVersionedDeterministicAndContainsOnlyPublicFamilies
15. BuildWithHQ.Integrations.Tests.DeveloperConnectorRegistryTests.MissingScopeDeniesBothTransportsBeforeRegistryRead
16. BuildWithHQ.Integrations.Tests.DeveloperConnectorRegistryTests.PublicRegistryContractsCannotSelectTenantOrPhysicalRouting
17. BuildWithHQ.Integrations.Tests.DeveloperConnectorRegistryTests.RegistryRejectsDuplicateTypesAndCapabilities
18. BuildWithHQ.Integrations.Tests.DeveloperConnectorRegistryTests.RestAndMcpReturnTheSameAuthorizedRegistry
19. BuildWithHQ.Integrations.Tests.DeveloperDataConnectorLiveDatabaseTests.ConnectorLifecycleIsScopedTypedAndRollbackOnly
20. BuildWithHQ.Integrations.Tests.DeveloperDataConnectorSqlContractTests.AuthoritativeExportContainsExactSecuredPublicBoundary
21. BuildWithHQ.Integrations.Tests.DeveloperDataConnectorSqlContractTests.LegacyWriterRetirementRequiresNoDependenciesOrGrants
22. BuildWithHQ.Integrations.Tests.DeveloperDataConnectorSqlContractTests.MigrationDerivesScopeAndLimitsPublicConnectorTypes
23. BuildWithHQ.Integrations.Tests.DeveloperDataConnectorSqlContractTests.MigrationGrantsOnlySecuredProceduresToTenantRuntime
24. BuildWithHQ.Integrations.Tests.DeveloperDataConnectorsTests.CrossAppTargetDeniesBothTransportsBeforeDatabaseRouting
25. BuildWithHQ.Integrations.Tests.DeveloperDataConnectorsTests.GraphQlConfigurationIsExactAndMutationOnly
26. BuildWithHQ.Integrations.Tests.DeveloperDataConnectorsTests.PublicContractRejectsInternalTypesRawSecretsAndReadOperations
27. BuildWithHQ.Integrations.Tests.DeveloperDataConnectorsTests.RestAndMcpReturnIdenticalAuthorizationForAllOperations
28. BuildWithHQ.Integrations.Tests.DeveloperDataConnectorsTests.ServiceUsesOnlyServerDerivedPrincipalAndCanonicalConfiguration
29. BuildWithHQ.Integrations.Tests.DeveloperInboundEndpointSqlContractTests.LiveExportUsesAuthorizationEnvelopeAndNeverReturnsStoredVerifier
30. BuildWithHQ.Integrations.Tests.DeveloperInboundEndpointSqlContractTests.RuntimeRoleHasOnlyExplicitProcedureExecutionGrants
31. BuildWithHQ.Integrations.Tests.DeveloperInboundEndpointsTests.CrossAppTargetDeniesBothTransportsBeforeDatabaseRouting
32. BuildWithHQ.Integrations.Tests.DeveloperInboundEndpointsTests.PublicCommandsCannotSelectTenantPrincipalOrPhysicalRouting
33. BuildWithHQ.Integrations.Tests.DeveloperInboundEndpointsTests.RestAndMcpReturnIdenticalAuthorizationForAllOperations
34. BuildWithHQ.Integrations.Tests.DeveloperInboundEndpointsTests.ServiceUsesOnlyServerDerivedPrincipalForProcedureParameters
35. BuildWithHQ.Integrations.Tests.DeveloperInstalledServicesTests.CrossAppTargetDeniesBothTransportsBeforeGatewayDispatch
36. BuildWithHQ.Integrations.Tests.DeveloperInstalledServicesTests.DefaultGatewayFailsClosedWithCorrelatedSafeError
37. BuildWithHQ.Integrations.Tests.DeveloperInstalledServicesTests.InvocationCommandValidatesKeysPayloadAndRecordTargets
38. BuildWithHQ.Integrations.Tests.DeveloperInstalledServicesTests.MissingInvocationScopeDeniesBothTransportsBeforeGatewayDispatch
39. BuildWithHQ.Integrations.Tests.DeveloperInstalledServicesTests.PublicInvocationCommandCannotSelectIdentityOrPhysicalRouting
40. BuildWithHQ.Integrations.Tests.DeveloperInstalledServicesTests.RestAndMcpShareAuthorizationIdentityAndGatewayBoundary
41. BuildWithHQ.Integrations.Tests.DeveloperInstalledServicesTests.UnboundApiClientFailsBeforeGatewayDispatch
42. BuildWithHQ.Integrations.Tests.DeveloperOAuthConnectionsTests.CrossAppTargetDeniesBothTransportsBeforeDatabaseRouting
43. BuildWithHQ.Integrations.Tests.DeveloperOAuthConnectionsTests.PublicCommandsCannotSelectTenantIdentityOrPhysicalRouting
44. BuildWithHQ.Integrations.Tests.DeveloperOAuthConnectionsTests.RestAndMcpReturnIdenticalAuthorizationForEveryOperation
45. BuildWithHQ.Integrations.Tests.DeveloperOAuthConnectionsTests.ServiceRoutesLifecycleThroughSecuredContractsUsingServerIdentity
46. BuildWithHQ.Integrations.Tests.DeveloperOAuthLiveDatabaseTests.OAuthLifecycleIsScopedLeasedOneTimeAndRollbackOnly
47. BuildWithHQ.Integrations.Tests.DeveloperOAuthSqlContractTests.AuthoritativeExportContainsTheSecuredOAuthTablesProceduresAndGrants
48. BuildWithHQ.Integrations.Tests.DeveloperOAuthSqlContractTests.EveryProcedureAuthorizesServerDerivedTenantScopeAndHasNoPhysicalRouteInput
49. BuildWithHQ.Integrations.Tests.DeveloperOAuthSqlContractTests.MigrationStoresOnlyProtectedTokensAndOneTimeHashedAuthorizationState
50. BuildWithHQ.Integrations.Tests.DeveloperOAuthSqlContractTests.RefreshAndRevokeUseBoundedLeasesAndRejectNullableOutcomes
51. BuildWithHQ.Integrations.Tests.DeveloperPaymentConnectorLiveDatabaseTests.ConnectorLifecycleIsScopedTypedAndRollbackOnly
52. BuildWithHQ.Integrations.Tests.DeveloperPaymentConnectorSqlContractTests.AuthoritativeExportContainsOnlyTheSecuredPublicBoundaryAndUnusedLegacyName
53. BuildWithHQ.Integrations.Tests.DeveloperPaymentConnectorSqlContractTests.LegacyWriterRetirementRequiresNoDependenciesReferencesOrGrants
54. BuildWithHQ.Integrations.Tests.DeveloperPaymentConnectorSqlContractTests.MigrationDerivesAccountAndIntegerAppScopeAfterAuthorization
55. BuildWithHQ.Integrations.Tests.DeveloperPaymentConnectorSqlContractTests.MigrationUsesOnlyOpaqueReferencesAndGrantsSecuredProcedures
56. BuildWithHQ.Integrations.Tests.DeveloperPaymentConnectorsTests.CrossAppTargetDeniesBothTransportsBeforeDatabaseRouting
57. BuildWithHQ.Integrations.Tests.DeveloperPaymentConnectorsTests.PublicContractIsStripeOnlyAndHasNoRawSecretOrEndpointFields
58. BuildWithHQ.Integrations.Tests.DeveloperPaymentConnectorsTests.RestAndMcpReturnIdenticalAuthorizationForAllOperations
59. BuildWithHQ.Integrations.Tests.DeveloperPaymentConnectorsTests.ServiceUsesOnlyServerDerivedPrincipalAndOpaqueReferences
60. BuildWithHQ.Integrations.Tests.DeveloperRecordsTests.CrossAppTargetDeniesBothTransportsBeforeTenantRouting
61. BuildWithHQ.Integrations.Tests.DeveloperRecordsTests.PublicRecordCommandsCannotSelectTenantOrPhysicalRouting
62. BuildWithHQ.Integrations.Tests.DeveloperRecordsTests.RestAndMcpAuthorizeEveryRecordOperationIdentically
63. BuildWithHQ.Integrations.Tests.DeveloperRecordsTests.RestAndMcpUseSameCoordinatorDecisionAndPayload
64. BuildWithHQ.Integrations.Tests.DeveloperRecordsTests.UnboundCredentialFailsBeforeExecutorCreation
65. BuildWithHQ.Integrations.Tests.DeveloperWebhookDeliverySqlContractTests.MigrationDefinesLeaseAuditRetryAndTenantBoundContracts
66. BuildWithHQ.Integrations.Tests.DeveloperWebhookSubscriptionSqlContractTests.LiveExportHasNormalizedFiltersEnvelopeScopeAndNoSecretInspection
67. BuildWithHQ.Integrations.Tests.DeveloperWebhookSubscriptionTests.CommandsRejectPrivateDestinationsAndPhysicalRoutingSelectors
68. BuildWithHQ.Integrations.Tests.DeveloperWebhookSubscriptionTests.CreateDisplaysRawSecretOnceButRoutesOnlyEncryptedEnvelope
69. BuildWithHQ.Integrations.Tests.DeveloperWebhookSubscriptionTests.DeliveryRestAndMcpAuthorizationOutcomesAreIdentical
70. BuildWithHQ.Integrations.Tests.DeveloperWebhookSubscriptionTests.RestAndMcpReturnIdenticalOutcomesAndCrossAppStopsBeforeService
71. BuildWithHQ.Integrations.Tests.DeveloperWebhookSubscriptionTests.SigningSecretsAreAuthenticatedEncryptedAndTamperEvident
72. BuildWithHQ.Integrations.Tests.OAuthProtocolTests.AesGcmProtectorRoundTripsRotatedKeysAndRejectsTamperingAndDomainConfusion
73. BuildWithHQ.Integrations.Tests.OAuthProtocolTests.StandardClientReturnsOnlySafeProviderErrors
74. BuildWithHQ.Integrations.Tests.OAuthProtocolTests.StandardClientUsesPkceBasicAuthenticationAndProviderOwnedEndpoints

**Marketplace — 50 passed**
1. BuildWithHQ.Marketplace.Tests.MarketplaceCatalogServiceTests.BuyerEntitlementReaderUsesOnlyVerifiedServerIdentity
2. BuildWithHQ.Marketplace.Tests.MarketplaceCatalogServiceTests.HistoricalEntitledVersionRemainsReinstallableWithoutChangingInstalledVersion
3. BuildWithHQ.Marketplace.Tests.MarketplaceCatalogServiceTests.PublicCatalogReturnsExactRecommendedVersionAndNormalizesCurrency
4. BuildWithHQ.Marketplace.Tests.MarketplaceCatalogServiceTests.TenantIdentityCannotReadControlPlaneEntitlements
5. BuildWithHQ.Marketplace.Tests.MarketplaceCatalogServiceTests.VersionCatalogRejectsCrossBuyerResultWithSafeError
6. BuildWithHQ.Marketplace.Tests.MarketplaceCheckoutServiceTests.FreeOrderReturnsGrantedExactVersionWithoutCallingStripe
7. BuildWithHQ.Marketplace.Tests.MarketplaceCheckoutServiceTests.PaidOrderUsesVerifiedBuyerScopeAndRegistersOneIdempotentProviderSession
8. BuildWithHQ.Marketplace.Tests.MarketplaceCheckoutServiceTests.ProviderFailureIsSafeAndLeavesOrderRetryableWithSameKey
9. BuildWithHQ.Marketplace.Tests.MarketplaceCheckoutServiceTests.TenantIdentityCannotCreateControlPlaneOrder
10. BuildWithHQ.Marketplace.Tests.MarketplaceCheckoutSqlContractTests.CheckoutSessionRegistrationIsBuyerScopedAndIdempotent
11. BuildWithHQ.Marketplace.Tests.MarketplaceCheckoutSqlContractTests.OrderItemsSnapshotProviderTermsExactlyOnce
12. BuildWithHQ.Marketplace.Tests.MarketplaceEntitlementAssignmentServiceTests.AssignmentUsesVerifiedBuyerAndReturnsExactGrantedVersionAndJob
13. BuildWithHQ.Marketplace.Tests.MarketplaceEntitlementAssignmentServiceTests.EmptyAssignmentIdentifiersAreRejectedBeforeDatabaseCall
14. BuildWithHQ.Marketplace.Tests.MarketplaceEntitlementAssignmentServiceTests.OutOfScopeAssignmentReceiptFailsClosed
15. BuildWithHQ.Marketplace.Tests.MarketplaceEntitlementAssignmentServiceTests.TenantIdentityCannotAssignControlPlaneEntitlement
16. BuildWithHQ.Marketplace.Tests.MarketplaceEntitlementAssignmentSqlContractTests.CurrentAssignmentContractEnforcesBuyerPermissionOwnershipAndExactVersionQueue
17. BuildWithHQ.Marketplace.Tests.MarketplaceEntitlementAssignmentSqlContractTests.ExactVersionQueueRequiresGrantAndRetainsWithdrawnReinstallability
18. BuildWithHQ.Marketplace.Tests.MarketplaceExactVersionSqlContractTests.BuyerVersionCatalogReturnsImmutableGrantLedgerAndVersionStatus
19. BuildWithHQ.Marketplace.Tests.MarketplaceExactVersionSqlContractTests.HistoricalEntitledVersionIsAnExactInstallCandidate
20. BuildWithHQ.Marketplace.Tests.MarketplaceExactVersionSqlContractTests.InstallJobSnapshotsSelectedVersionAndArtifactFingerprints
21. BuildWithHQ.Marketplace.Tests.MarketplaceExactVersionSqlContractTests.TemplatePayloadBridgeRetainsArchivedExactVersionAccess
22. BuildWithHQ.Marketplace.Tests.MarketplaceInstallRequestServiceTests.DifferentReturnedVersionFailsClosed
23. BuildWithHQ.Marketplace.Tests.MarketplaceInstallRequestServiceTests.EmptyVersionIsRejectedBeforeDatabaseCall
24. BuildWithHQ.Marketplace.Tests.MarketplaceInstallRequestServiceTests.ExactHistoricalVersionRequestUsesVerifiedBuyerAndReturnsDurableJob
25. BuildWithHQ.Marketplace.Tests.MarketplaceInstallRequestServiceTests.TenantIdentityCannotRequestControlPlaneInstall
26. BuildWithHQ.Marketplace.Tests.MarketplaceInstallRequestServiceTests.UpgradeApplyCarriesExactCurrentVersionFence
27. BuildWithHQ.Marketplace.Tests.MarketplaceInstallRequestServiceTests.UpgradePreviewReturnsDriftAndRollbackEvidenceFromVerifiedBuyerScope
28. BuildWithHQ.Marketplace.Tests.MarketplaceInstallRequestSqlContractTests.InternalQueueIsAtomicIdempotentAndSnapshotsExactComponents
29. BuildWithHQ.Marketplace.Tests.MarketplaceInstallRequestSqlContractTests.PublicRequestDerivesBuyerTargetAndQueuesOnlySelectedEntitledVersion
30. BuildWithHQ.Marketplace.Tests.MarketplaceLicenseLifecycleServiceTests.DisableRequiresReasonBeforeDatabaseCall
31. BuildWithHQ.Marketplace.Tests.MarketplaceLicenseLifecycleServiceTests.RequestDerivesBuyerAndActorAndReturnsExactQueuedAction
32. BuildWithHQ.Marketplace.Tests.MarketplaceLicenseLifecycleServiceTests.StatusLookupIsBuyerScopedAndChecksExactActionIdentity
33. BuildWithHQ.Marketplace.Tests.MarketplaceLicenseLifecycleSqlContractTests.LicenseLifecycleIsFencedIdempotentAndProcedureOnly
34. BuildWithHQ.Marketplace.Tests.MarketplacePayoutServiceTests.InvalidRequestIsRejectedBeforeDatabaseCall
35. BuildWithHQ.Marketplace.Tests.MarketplacePayoutServiceTests.RequestDerivesSellerActorAndCorrelationAndReturnsExactReplayIdentity
36. BuildWithHQ.Marketplace.Tests.MarketplacePayoutServiceTests.SummaryReturnsBalancesHistoryAndReconciliationState
37. BuildWithHQ.Marketplace.Tests.MarketplacePayoutSqlContractTests.PayoutPolicyIsIdempotentReconciledAndProcedureOnly
38. BuildWithHQ.Marketplace.Tests.MarketplaceProductOfferSqlContractTests.SellerCatalogAndAvailabilityStayOwnedProcedureOnlyAndSnapshotSafe
39. BuildWithHQ.Marketplace.Tests.MarketplaceSellerConsoleSqlContractTests.SellerReadsAreProcedureOnlyScopedAndKeepFinancePermissionsSeparate
40. BuildWithHQ.Marketplace.Tests.MarketplaceSellerOnboardingServiceTests.CreateUsesOnlyServerDerivedScopeAndReturnsRedactedStatus
41. BuildWithHQ.Marketplace.Tests.MarketplaceSellerOnboardingServiceTests.ReturnedAccountMismatchFailsClosed
42. BuildWithHQ.Marketplace.Tests.MarketplaceSellerOnboardingServiceTests.TenantIdentityCannotUseSellerControlPlane
43. BuildWithHQ.Marketplace.Tests.MarketplaceSellerOnboardingServiceTests.TermsAcceptanceCarriesExactVersionAndCorrelation
44. BuildWithHQ.Marketplace.Tests.MarketplaceSellerOnboardingServiceTests.UnsafeProfileUrlIsRejectedBeforeDatabaseCall
45. BuildWithHQ.Marketplace.Tests.MarketplaceSellerOnboardingSqlContractTests.SellerOnboardingUsesOpaqueReferencesSafeProjectionAndProcedureOnlyGrants
46. BuildWithHQ.Marketplace.Tests.MarketplaceUpgradeSqlContractTests.PreviewAndApplyRequireEntitlementExactVersionAndStalePreviewFence
47. BuildWithHQ.Marketplace.Tests.StripeMarketplaceCheckoutGatewayTests.OneTimeFallbackCreatesPriceDataWithoutExposingSecret
48. BuildWithHQ.Marketplace.Tests.StripeMarketplaceCheckoutGatewayTests.OptionsRejectNonHttpsRedirectsAndMissingSecrets
49. BuildWithHQ.Marketplace.Tests.StripeMarketplaceCheckoutGatewayTests.ProviderErrorReturnsSafeExceptionWithoutResponseBody
50. BuildWithHQ.Marketplace.Tests.StripeMarketplaceCheckoutGatewayTests.SubscriptionCheckoutUsesServerUrlsSecretHeaderAndImmutableProviderPrice

**Security services — 37 passed**
1. BuildWithHQ.Security.Tests.AuthorizationReplayServiceTests.BuilderAndAnonymousContextsAreDeniedBeforeResolution
2. BuildWithHQ.Security.Tests.AuthorizationReplayServiceTests.CallerSuppliedOwnerSnapshotCannotBypassRevalidation
3. BuildWithHQ.Security.Tests.AuthorizationReplayServiceTests.InvalidTargetAndModeAreRejectedBeforeResolution
4. BuildWithHQ.Security.Tests.AuthorizationReplayServiceTests.MismatchedEnvelopeAndMalformedResultFailClosed
5. BuildWithHQ.Security.Tests.AuthorizationReplayServiceTests.NonOwnerIsDeniedAfterDatabaseEnvelopeResolution
6. BuildWithHQ.Security.Tests.AuthorizationReplayServiceTests.OwnerReplayUsesRevalidatedServerScopeAndParsesEvidence
7. BuildWithHQ.Security.Tests.CanonicalPermissionKeyEvaluatorTests.AllowsGrantedPermissionWithCanonicalCaseInsensitiveComparison
8. BuildWithHQ.Security.Tests.CanonicalPermissionKeyEvaluatorTests.AllowsNullRequiredPermissionForRevalidatedTenantOnly
9. BuildWithHQ.Security.Tests.CanonicalPermissionKeyEvaluatorTests.AuditsAllowedAndDeniedPermissionDecisionsWithoutCallerScope
10. BuildWithHQ.Security.Tests.CanonicalPermissionKeyEvaluatorTests.DeniesBootstrapClaimsUntilDatabaseAuthorizationIsAttached
11. BuildWithHQ.Security.Tests.CanonicalPermissionKeyEvaluatorTests.DeniesInvalidRequiredPermissionDeterministically
12. BuildWithHQ.Security.Tests.CanonicalPermissionKeyEvaluatorTests.DeniesMissingPermissionWithoutAccountOwnerBypass
13. BuildWithHQ.Security.Tests.CanonicalPermissionKeyEvaluatorTests.DeniesNonTenantIdentityBeforePermissionMatch
14. BuildWithHQ.Security.Tests.CanonicalPermissionKeyEvaluatorTests.PublicEvaluatorAcceptsNoCallerTenantScope
15. BuildWithHQ.Security.Tests.EncryptedDynamicFieldAccessTests.AnonymousAndInvalidResourceIdsFailBeforeSql
16. BuildWithHQ.Security.Tests.EncryptedDynamicFieldAccessTests.AuthorizedRevealUsesOnlyServerIdentityAndReturnsRedactedSensitiveValue
17. BuildWithHQ.Security.Tests.EncryptedDynamicFieldAccessTests.BuilderPlaneIsDeniedBeforeSqlOrKeyResolution
18. BuildWithHQ.Security.Tests.EncryptedDynamicFieldAccessTests.DisposedSensitiveValueCannotBeRevealedAgain
19. BuildWithHQ.Security.Tests.EncryptedDynamicFieldAccessTests.MalformedOrUnsupportedEnvelopeFailsWithoutKeyResolution
20. BuildWithHQ.Security.Tests.EncryptedDynamicFieldAccessTests.MissingKeyInfrastructureFailsClosedAfterAuthorizedSqlGate
21. BuildWithHQ.Security.Tests.EncryptedDynamicFieldAccessTests.StructuredLoggingRedactsPlaintextAndEnvelopeMetadata
22. BuildWithHQ.Security.Tests.EncryptedDynamicFieldAccessTests.TamperedCiphertextFailsIntegrityWithoutReturningPlaintext
23. BuildWithHQ.Security.Tests.FeatureEntitlementEvaluatorTests.CacheIsTenantScopedAndCachedSnapshotUsesCurrentCorrelation
24. BuildWithHQ.Security.Tests.FeatureEntitlementEvaluatorTests.RequirementsAreTypedAndCacheDurationIsStrictlyBounded
25. BuildWithHQ.Security.Tests.FeatureEntitlementEvaluatorTests.RevocationBlocksWithoutRedeployAfterShortCacheAndImmediateInvalidation
26. BuildWithHQ.Security.Tests.FeatureEntitlementEvaluatorTests.ServiceIdentityCannotCheckAnotherAppsEntitlement
27. BuildWithHQ.Security.Tests.FeatureEntitlementEvaluatorTests.SourceFailureFailsClosedAndIsBrieflyCached
28. BuildWithHQ.Security.Tests.SecretProviderTests.ExternalProductionAdapterPreservesNameAndVersionWithoutLoggingValue
29. BuildWithHQ.Security.Tests.SecretProviderTests.LocalEnvironmentProviderIsPrefixBoundAndCompositeRoutesByProvider
30. BuildWithHQ.Security.Tests.SecretProviderTests.MountedProductionProviderReadsOnlyBeneathConfiguredRoot
31. BuildWithHQ.Security.Tests.SecretProviderTests.SecretValueRedactsJsonStringFormattingAndStructuredLogs
32. BuildWithHQ.Security.Tests.SecretProviderTests.SharedReferenceContainsIdentifiersButCannotCarryResolvedMaterial
33. BuildWithHQ.Security.Tests.TrustedAuthorizationEnvelopeResolverTests.AllowsScopedEnvelopeWithNoActiveLocationsToFailClosedLater
34. BuildWithHQ.Security.Tests.TrustedAuthorizationEnvelopeResolverTests.EnvelopeRejectsLocationsWhenDatabaseSaysUnscoped
35. BuildWithHQ.Security.Tests.TrustedAuthorizationEnvelopeResolverTests.LoadsEnvelopeOnlyFromVerifiedIdentityAndDatabasePayload
36. BuildWithHQ.Security.Tests.TrustedAuthorizationEnvelopeResolverTests.RejectsDatabasePayloadForDifferentTenantIdentity
37. BuildWithHQ.Security.Tests.TrustedAuthorizationEnvelopeResolverTests.RejectsNonTenantContextBeforeDatabaseExecution

**Builder Console UI — 188 passed**
1. AccountExperiencePages.test.tsx — account experience pages keeps required security notifications enabled
2. AccountExperiencePages.test.tsx — account experience pages loads and saves branding with only reviewed fields
3. AccountExperiencePages.test.tsx — account experience pages preserves communication settings when changing locale preferences
4. AccountSettingsPage.test.tsx — account settings page loads and saves profile fields while preserving server-owned scope
5. AccountSettingsPage.test.tsx — account settings page shows safe load, empty, and retry states
6. AccountSettingsPage.test.tsx — account settings page turns an optimistic concurrency failure into an actionable conflict
7. AiOperationsPage.test.tsx — AI operations dashboard refreshes on demand
8. AiOperationsPage.test.tsx — AI operations dashboard renders a safe denial without backend details
9. AiOperationsPage.test.tsx — AI operations dashboard shows worker, endpoint, queue, failure, throughput, and latency signals
10. ApiClientManagementPage.test.tsx — API client management confirms rotation and revocation and never offers lifecycle actions for revoked clients
11. ApiClientManagementPage.test.tsx — API client management creates with only app-targeted name and selected scopes, then displays the credential once
12. ApiClientManagementPage.test.tsx — API client management moves from loading to the empty state without inventing clients
13. ApiClientManagementPage.test.tsx — API client management renders server catalog scopes and schema-backed client state
14. ApiClientManagementPage.test.tsx — API client management uses safe permission errors without exposing backend details
15. AppObservabilityPages.test.tsx — app observability pages renders bounded usage and reloads only supported windows
16. AppObservabilityPages.test.tsx — app observability pages renders only safe log projections and sends bounded filters
17. ApplianceAuthoringPage.test.tsx — ApplianceAuthoringPage blocks install preview for an unpublished version
18. ApplianceAuthoringPage.test.tsx — ApplianceAuthoringPage lists owned packages through the native appliance route
19. ApplianceAuthoringPage.test.tsx — ApplianceAuthoringPage queues validation for the exact selected version
20. ApplianceAuthoringPage.test.tsx — ApplianceAuthoringPage shows exact endpoint permissions and no worker lease material
21. AppsPage.test.tsx — AppsPage polls a provisioning portfolio until its status settles
22. AppsPage.test.tsx — AppsPage renders a loading state while the portfolio request is pending
23. AppsPage.test.tsx — AppsPage renders a safe error with correlation and retries
24. AppsPage.test.tsx — AppsPage renders app data in the success state
25. AppsPage.test.tsx — AppsPage renders the empty state
26. AppsPage.test.tsx — AppsPage requires confirmation and replaces the card with the suspended result
27. AuditViewerPage.test.tsx — builder audit viewer loads older events using only the server continuation cursor
28. AuditViewerPage.test.tsx — builder audit viewer moves from loading to safe account-scoped audit events
29. AuditViewerPage.test.tsx — builder audit viewer renders valid empty and permission-denied states
30. AuditViewerPage.test.tsx — builder audit viewer searches loaded safe fields and applies an exact server action filter
31. BackupManagementPage.test.tsx — backup management moves from loading to empty history
32. BackupManagementPage.test.tsx — backup management requests only the selected server-known destination
33. BackupManagementPage.test.tsx — backup management saves metadata without credentials and renders safe errors
34. BackupManagementPage.test.tsx — backup management shows destinations and completed restore points
35. BillingHistoryPage.test.tsx — billing history allows retry after a safe transient failure
36. BillingHistoryPage.test.tsx — billing history keeps database/provider errors out of permission-denied output
37. BillingHistoryPage.test.tsx — billing history renders subscription, integer-money invoices, payments, refunds, and safe documents
38. BillingHistoryPage.test.tsx — billing history renders valid empty history
39. BillingHistoryPage.test.tsx — billing history requires explicit confirmation and shows a safe cancellation receipt
40. BillingResourcesPage.test.tsx — billing resources connects the server-derived payment customer without profile input
41. BillingResourcesPage.test.tsx — billing resources creates add-on checkout from the server catalog code
42. BillingResourcesPage.test.tsx — billing resources creates checkout from the internal plan target and exposes only the safe continuation link
43. BillingResourcesPage.test.tsx — billing resources renders permission denial without retry or database details
44. BillingResourcesPage.test.tsx — billing resources renders valid no-plan and no-add-on empty states
45. BillingResourcesPage.test.tsx — billing resources shows a safe correlation reference when customer mapping fails
46. BillingResourcesPage.test.tsx — billing resources shows plan, capacity, allocated usage and add-ons
47. CostTelemetryPanel.test.tsx — shows account/app estimates and makes missing rates explicit
48. CostTelemetryPanel.test.tsx — shows an honest empty state when no usage has arrived
49. DomainManagementPage.test.tsx — domain management adds a normalized target without browser identity or provider status
50. DomainManagementPage.test.tsx — domain management renders schema-backed domain and certificate states
51. DomainManagementPage.test.tsx — domain management shows provider DNS proof and refreshes after verification
52. DomainManagementPage.test.tsx — domain management uses row-versioned primary changes and safe forbidden errors
53. FeatureCatalogPage.test.tsx — console feature coverage accounts for every route in the 87-page audited prototype manifest exactly once
54. FeatureCatalogPage.test.tsx — console feature coverage renders the complete cross-console directory with honest readiness totals
55. FeatureCatalogPage.test.tsx — console feature coverage routes the promoted registration contract to the production form
56. HarnessConsolePages.test.tsx — Harness console parity pages shows aggregate exact-version inventory without tenant routing
57. HarnessConsolePages.test.tsx — Harness console parity pages shows bounded per-case results and queues only an exact route version
58. HarnessPackEditorPage.test.tsx — Harness Pack editor creates a normalized account-owned pack without caller scope fields
59. HarnessPackEditorPage.test.tsx — Harness Pack editor submits the selected typed component payload
60. HarnessPackEditorPage.test.tsx — Harness Pack editor surfaces owned components, tests, and exact version state
61. IntegrationManagementPage.test.tsx — integration management edits with row-version concurrency and renders safe provider errors
62. IntegrationManagementPage.test.tsx — integration management moves from loading to the schema-backed empty state
63. IntegrationManagementPage.test.tsx — integration management shows configured state without returning the secret reference
64. IntegrationManagementPage.test.tsx — integration management submits a secret reference identifier without any raw secret field
65. MarketplaceAdministrationPage.test.tsx — marketplace administration creates a seller-owned product without identity fields
66. MarketplaceAdministrationPage.test.tsx — marketplace administration keeps offer price and activation as explicit lifecycle actions
67. MarketplaceAdministrationPage.test.tsx — marketplace administration offers first-time seller profile setup
68. MarketplaceAdministrationPage.test.tsx — marketplace administration renders empty and correlation-safe error states
69. MarketplaceAdministrationPage.test.tsx — marketplace administration renders seller product and publication counts
70. MarketplaceCheckoutPage.test.tsx — Marketplace checkout page finishes a free order at the exact entitlement without a provider redirect
71. MarketplaceCheckoutPage.test.tsx — Marketplace checkout page reviews the exact version and redirects a paid order to the secure provider
72. MarketplaceCheckoutPage.test.tsx — Marketplace checkout page shows safe provider errors and preserves the order idempotency correlation on retry
73. MarketplacePages.test.tsx — Marketplace catalog pages assigns an unassigned exact-version entitlement to an owned SaaS app
74. MarketplacePages.test.tsx — Marketplace catalog pages discovers the current immutable version and applies safe catalog filters
75. MarketplacePages.test.tsx — Marketplace catalog pages keeps installed v1 separate from entitled v2 and exposes withdrawn v1 for reinstall
76. MarketplacePages.test.tsx — Marketplace catalog pages queues an explicitly selected withdrawn version without substituting entitled v2
77. MarketplacePages.test.tsx — Marketplace catalog pages renders a safe correlated entitlement-assignment conflict
78. MarketplacePages.test.tsx — Marketplace catalog pages renders a safe correlated marketplace failure and supports retry
79. MarketplacePages.test.tsx — Marketplace catalog pages shows a safe correlated error when an exact install request conflicts
80. MarketplacePages.test.tsx — Marketplace catalog pages shows product pricing and the exact compatibility component manifest
81. MarketplaceSellerPages.test.tsx — marketplace seller routes promotes all nine audited seller routes to native production pages
82. MarketplaceSellerPages.test.tsx — marketplace seller routes renders dashboard counts from the scoped seller catalog
83. MarketplaceSellerPages.test.tsx — marketplace seller routes renders gross, fee, net, and available values from the revenue contract
84. MarketplaceSellerPages.test.tsx — marketplace seller routes requires explicit confirmation and sends an idempotency key for payout
85. MfaFlow.test.tsx — builder MFA flow associates safe sign-in validation errors with both credential fields
86. MfaFlow.test.tsx — builder MFA flow completes a cookie-bound MFA challenge before opening the console
87. MfaFlow.test.tsx — builder MFA flow enrolls and activates MFA from authenticated settings without identity input
88. OwnershipTransferPage.test.tsx — ownership transfer page does not load team data for a non-owner
89. OwnershipTransferPage.test.tsx — ownership transfer page shows only eligible administrators and signs out after an acknowledged transfer
90. PortfolioPages.test.tsx — AppOpenPage loads the ownership-validated app and shows provisioning state
91. PortfolioPages.test.tsx — AppOpenPage renders the same safe not-found state for unavailable apps
92. PortfolioPages.test.tsx — AppOpenPage renders valid empty states for builder-only apps without domains, quota, or a container
93. PortfolioPages.test.tsx — CreateAppPage explains plan-limit failures without exposing internals
94. PortfolioPages.test.tsx — CreateAppPage preserves the correlation id across a safe retry and opens the created app
95. ProvisioningProgressPage.test.tsx — ProvisioningProgressPage polls durable state until the job is terminal
96. ProvisioningProgressPage.test.tsx — ProvisioningProgressPage renders durable step state and support correlation without provider internals
97. ProvisioningProgressPage.test.tsx — ProvisioningProgressPage shows safe retry failure details and durable failure code
98. PublicAuthPages.test.tsx — public builder authentication pages keeps password reset requests enumeration resistant
99. PublicAuthPages.test.tsx — public builder authentication pages renders a safe invalid verification state without a token
100. PublicAuthPages.test.tsx — public builder authentication pages resolves then accepts an invitation without returning the raw token to the page
101. PublicAuthPages.test.tsx — public builder authentication pages submits registration without database or authorization selectors
102. ResourceAllocationPanel.test.tsx — resource allocation panel keeps dependency details out of load failures
103. ResourceAllocationPanel.test.tsx — resource allocation panel prevents allocations below measured usage and disables fixed workspaces
104. ResourceAllocationPanel.test.tsx — resource allocation panel shows per-app allocations and submits only bounded allocation fields
105. RolePermissionsPage.test.tsx — role permissions page renders the complete built-in role permission matrix and assignment link
106. RolePermissionsPage.test.tsx — role permissions page shows a safe correlated error and supports retry
107. RolePermissionsPage.test.tsx — role permissions page shows an explicit empty state
108. RuntimeControlPage.test.tsx — runtime control moves from loading to technology-neutral status and safe event pointers
109. RuntimeControlPage.test.tsx — runtime control renders a correlated API error without provider details
110. RuntimeControlPage.test.tsx — runtime control renders a valid empty state for a builder-only app
111. RuntimeControlPage.test.tsx — runtime control restarts through the server endpoint and shows the correlation receipt
112. SecurityCenterPage.test.tsx — security center keeps sessions usable when audit permission is denied and hides raw errors
113. SecurityCenterPage.test.tsx — security center revokes a non-current session without signing out
114. SecurityCenterPage.test.tsx — security center shows current sessions and recent permitted audit context
115. SecurityCenterPage.test.tsx — security center signs out locally only after all-session revocation succeeds
116. Shell.test.tsx — AuthenticatedShell closes navigation with Escape and restores focus to its toggle
117. Shell.test.tsx — AuthenticatedShell exposes mobile navigation state and closes it after navigation
118. Shell.test.tsx — AuthenticatedShell focuses operations navigation without adding a new authorization gate
119. Shell.test.tsx — AuthenticatedShell keeps account administration focused in the admin console
120. Shell.test.tsx — AuthenticatedShell keeps the shell behind the sign-in session gate
121. Shell.test.tsx — AuthenticatedShell makes the appliance template marketplace first-class in the developer console
122. Shell.test.tsx — AuthenticatedShell mounts the current app portfolio in authenticated navigation
123. Shell.test.tsx — AuthenticatedShell moves programmatic focus to the main landmark after route navigation
124. Shell.test.tsx — AuthenticatedShell navigates between registered destinations and updates the topbar
125. Shell.test.tsx — AuthenticatedShell promotes ownership transfer to its native protected workflow
126. Shell.test.tsx — AuthenticatedShell recognizes the SaaS creation route in the shell title
127. Shell.test.tsx — AuthenticatedShell renders a safe not-found route and signs out from the shell
128. Shell.test.tsx — RouteErrorBoundary contains render failures and resets when the route changes
129. SnowflakeConfigurationPage.test.tsx — Snowflake destination configuration creates a destination with an opaque reference and no secret-value field
130. SnowflakeConfigurationPage.test.tsx — Snowflake destination configuration renders a safe owner authorization error
131. SnowflakeConfigurationPage.test.tsx — Snowflake destination configuration renders safe configured metadata without a credential reference
132. SnowflakeConfigurationPage.test.tsx — Snowflake destination configuration retains the configured credential and submits row-version concurrency on update
133. SnowflakeConfigurationPage.test.tsx — Snowflake destination configuration retries only the selected failed run and refreshes server-derived history
134. SnowflakeConfigurationPage.test.tsx — Snowflake destination configuration shows run counts, failure evidence, and the current successful checkpoint
135. SnowflakeConfigurationPage.test.tsx — Snowflake destination configuration tests the configured destination and shows only the safe receipt
136. SnowflakeConfigurationPage.test.tsx — Snowflake destination configuration updates recurring cadence without client-supplied tenant identity
137. TeamPage.test.tsx — team page invites through the server contract and reloads the snapshot
138. TeamPage.test.tsx — team page renders members, owner protection, roles, and pending invitations
139. TeamPage.test.tsx — team page shows safe load and conflict failures
140. TeamPage.test.tsx — team page updates role, deactivates a member, and revokes invitations with row-version inputs
141. TemplateAdministrationPage.test.tsx — template administration archives only the displayed immutable version
142. TemplateAdministrationPage.test.tsx — template administration creates a minimal language-safe draft
143. TemplateAdministrationPage.test.tsx — template administration renders owned publication state and validates a working copy
144. TemplateAdministrationPage.test.tsx — template administration renders valid empty and correlation-safe error states
145. TemplateAuthoringPage.test.tsx — TemplateAuthoringPage creates a typed draft through the authoring API seam
146. TemplateAuthoringPage.test.tsx — TemplateAuthoringPage renders secured production catalog data and owned version links
147. UsageAlertsPanel.test.tsx — usage alerts panel does not expose dependency details in failures
148. UsageAlertsPanel.test.tsx — usage alerts panel renders a clear state when no threshold is active
149. UsageAlertsPanel.test.tsx — usage alerts panel renders scoped operational notices with current threshold evidence
150. api.test.ts — builder API client assigns an entitlement to an app without caller-controlled buyer identity
151. api.test.ts — builder API client creates a marketplace order with stable correlation and no caller-controlled buyer identity
152. api.test.ts — builder API client creates add-on checkout with only the selected internal catalog code
153. api.test.ts — builder API client creates an app with a stable correlation and no routing input
154. api.test.ts — builder API client creates platform checkout with only the selected internal plan target
155. api.test.ts — builder API client loads and updates app allocation without caller-controlled account scope
156. api.test.ts — builder API client loads apps with the bearer token and no caller-controlled account scope
157. api.test.ts — builder API client loads billing resources without caller-controlled account scope
158. api.test.ts — builder API client loads bounded billing history without provider or account selectors
159. api.test.ts — builder API client loads cost telemetry with only an optional UTC month selector
160. api.test.ts — builder API client loads the sanitized billing catalog without provider or account input
161. api.test.ts — builder API client loads usage alerts without account, database, or threshold selectors
162. api.test.ts — builder API client logs in through the auth service contract
163. api.test.ts — builder API client maps the payment customer with an empty authenticated server-scoped request
164. api.test.ts — builder API client opens and suspends only the target app resource
165. api.test.ts — builder API client reads AI operations with only a bounded lookback query
166. api.test.ts — builder API client reads and updates account profile without caller-controlled identity or database scope
167. api.test.ts — builder API client reads the built-in role permission matrix from the server-scoped endpoint
168. api.test.ts — builder API client reads the target app provisioning contract without caller-controlled scope
169. api.test.ts — builder API client requests an exact entitled version without caller-controlled app or buyer scope
170. api.test.ts — builder API client requests period-end cancellation without account or provider identifiers
171. api.test.ts — builder API client uses account-scoped template administration routes and exact archive versions
172. api.test.ts — builder API client uses app-scoped API-client lifecycle routes without browser-controlled identity or secret hashes
173. api.test.ts — builder API client uses app-scoped backup routes without database or cloud credentials
174. api.test.ts — builder API client uses app-scoped integration routes with references but no secret values or caller identity
175. api.test.ts — builder API client uses app-targeted domain routes without accepting account or provider truth
176. api.test.ts — builder API client uses cookie-bound MFA routes without caller-controlled account scope
177. api.test.ts — builder API client uses exact Harness evaluation and aggregate inventory routes without tenant routing
178. api.test.ts — builder API client uses marketplace administration lifecycle routes without caller-controlled seller scope
179. api.test.ts — builder API client uses only bounded audit filters and an opaque continuation cursor
180. api.test.ts — builder API client uses owner-derived Harness Pack routes and exact version identity
181. api.test.ts — builder API client uses owner-derived appliance authoring routes without database or worker scope
182. api.test.ts — builder API client uses security readers and auth revocation routes without browser-supplied account scope
183. api.test.ts — builder API client uses separated seller catalog, revenue, payout, artifact, and composition routes
184. api.test.ts — builder API client uses stable marketplace read routes without caller-controlled buyer identity
185. api.test.ts — builder API client uses team routes without caller-controlled account, actor, token, or provider scope
186. webSecurity.test.ts — web security request proof adds proof only to unsafe requests
187. webSecurity.test.ts — web security request proof creates and reuses a host-scoped CSRF token
188. webSecurity.test.ts — web security request proof does not overwrite an unrelated authorization header

**Tenant runtime UI — 184 passed**
1. ActiveWorkplaceContract.test.ts — ActiveWorkplace contracts accepts bounded current detail
2. ActiveWorkplaceContract.test.ts — ActiveWorkplace contracts accepts read-only playback with current-permission graph output
3. ActiveWorkplaceContract.test.ts — ActiveWorkplace contracts rejects playback unless the server marks it read only
4. ActiveWorkplaceModule.test.tsx — ActiveWorkplace first-class module pins a currently visible universal record
5. ActiveWorkplaceModule.test.tsx — ActiveWorkplace first-class module removes every mutation control in Graph Playback
6. App.test.tsx — tenant runtime app does not display a malformed page payload
7. App.test.tsx — tenant runtime app navigates using only page keys from the authorized tenant shell
8. App.test.tsx — tenant runtime app resolves a deep-link pathname through the secured slug route
9. App.test.tsx — tenant runtime app shows Design only when login returns the exact authorized builder session
10. App.test.tsx — tenant runtime app signs in and displays the authorized runtime page contract
11. CalendarContract.test.ts — Calendar module contracts fails closed on malformed identities, timestamps, and versions
12. CalendarContract.test.ts — Calendar module contracts parses versioned universal records and normalizes SQL datetime2 values as UTC
13. CalendarModule.test.tsx — Calendar first-class module creates an event without submitting tenant identity fields
14. CalendarModule.test.tsx — Calendar first-class module loads secured events and exposes attendees, relations, activity, fields, and favorites
15. CalendarModule.test.tsx — Calendar first-class module shows a safe empty state for an empty secured result
16. ChatRoomsContract.test.ts — Chat rooms contract parses secured list and detail contracts
17. ChatRoomsContract.test.ts — Chat rooms contract parses typed collaboration mutations
18. ChatRoomsContract.test.ts — Chat rooms contract rejects malformed identities, room types, and nested contracts
19. ChatRoomsModule.test.tsx — Chat rooms first-class module creates a room without caller-controlled tenant scope
20. ChatRoomsModule.test.tsx — Chat rooms first-class module hides authoring controls from readers
21. ChatRoomsModule.test.tsx — Chat rooms first-class module opens a secured room and performs message, reaction, and mute actions
22. CompanyNewsContract.test.ts — Company news module contracts fails closed on malformed identities, timestamps, and versions
23. CompanyNewsContract.test.ts — Company news module contracts parses versioned universal record, publishing, and dynamic-field contracts
24. CompanyNewsModule.test.tsx — Company news first-class module creates an announcement without sending caller-controlled tenant scope
25. CompanyNewsModule.test.tsx — Company news first-class module hides authoring controls and shows a safe empty state for a reader
26. CompanyNewsModule.test.tsx — Company news first-class module loads secured news and exposes publishing, relations, activity, fields, and favorites
27. ContactsContract.test.ts — Contacts module contracts fails closed on malformed identities and versions
28. ContactsContract.test.ts — Contacts module contracts parses versioned universal record contracts
29. ContactsModule.test.tsx — Contacts first-class module composes a team directory from secured employee and contractor contact types
30. ContactsModule.test.tsx — Contacts first-class module creates a contact without submitting tenant identity fields
31. ContactsModule.test.tsx — Contacts first-class module loads secured records and exposes relations, activity, fields, and favorites
32. ContactsModule.test.tsx — Contacts first-class module shows a safe empty state for an empty secured result
33. ConversationsContract.test.ts — Conversations module contracts fails closed on malformed scope data and private storage metadata
34. ConversationsContract.test.ts — Conversations module contracts parses universal detail, messages, relations, favorites, and dynamic fields
35. ConversationsModule.test.tsx — Conversations first-class module creates an internal conversation without browser-supplied tenant identity
36. ConversationsModule.test.tsx — Conversations first-class module loads the secured native thread with universal activity, relations, fields, and favorites
37. ConversationsModule.test.tsx — Conversations first-class module shows a safe empty state
38. ConversationsModule.test.tsx — Conversations first-class module updates conversation state and posts through the reviewed message path
39. DiscussionBoardsContract.test.ts — Discussion boards contract parses secured board and topic graphs
40. DiscussionBoardsContract.test.ts — Discussion boards contract parses typed mutations
41. DiscussionBoardsContract.test.ts — Discussion boards contract rejects malformed identities and nested contracts
42. DiscussionBoardsModule.test.tsx — Discussion boards first-class module creates a board without caller-controlled tenant scope
43. DiscussionBoardsModule.test.tsx — Discussion boards first-class module hides authoring controls from readers
44. DiscussionBoardsModule.test.tsx — Discussion boards first-class module opens a topic, posts a reply, and edits an owned post
45. DynamicModulesContract.test.ts — Dynamic module contracts parses schema-driven records and universal context
46. DynamicModulesContract.test.ts — Dynamic module contracts rejects malformed module keys, identities, and timestamps
47. DynamicModulesModule.test.tsx — Dynamic records first-class module fails closed when the page block has no module key
48. DynamicModulesModule.test.tsx — Dynamic records first-class module uses configured module key and exposes fields, relations, activity, and favorites
49. FavoritesContract.test.ts — Favorites contract parses preference and removal mutations
50. FavoritesContract.test.ts — Favorites contract parses secured list and universal detail data
51. FavoritesContract.test.ts — Favorites contract rejects malformed identities and nested contracts
52. FavoritesModule.test.tsx — Favorites first-class module filters without sending caller identity
53. FavoritesModule.test.tsx — Favorites first-class module opens a secured favorite and updates pin preferences
54. FavoritesModule.test.tsx — Favorites first-class module removes by universal record identity
55. FilesContract.test.ts — Files module contracts fails closed on malformed identity, timestamps, versions, and leaked storage keys
56. FilesContract.test.ts — Files module contracts parses secured universal file details without storage metadata
57. FilesModule.test.tsx — Files first-class module loads secured details with attachments, activity, locks, fields, and favorites
58. FilesModule.test.tsx — Files first-class module shows a safe empty state
59. FilesModule.test.tsx — Files first-class module updates metadata and adds or removes secured attachment links
60. FilesModule.test.tsx — Files first-class module uploads bytes without caller-controlled tenant or storage metadata
61. FormsRuntime.test.tsx — forms runtime parses bounded presentation definitions and validates typed values
62. FormsRuntime.test.tsx — forms runtime renders safe controls and submits only definition-owned values
63. GlobalSearchContract.test.ts — Global search contract accepts an empty-query module bootstrap contract
64. GlobalSearchContract.test.ts — Global search contract parses secured record results and safe matched fields
65. GlobalSearchContract.test.ts — Global search contract rejects malformed identities, states, and nested fields
66. GlobalSearchModule.test.tsx — Global secured search first-class module applies module filters and rejects a one-character query locally
67. GlobalSearchModule.test.tsx — Global secured search first-class module requests the next bounded result page
68. GlobalSearchModule.test.tsx — Global secured search first-class module searches secured records and toggles canonical favorite state
69. KnowledgeArticlesContract.test.ts — Knowledge articles module contracts fails closed on malformed identities, timestamps, and versions
70. KnowledgeArticlesContract.test.ts — Knowledge articles module contracts parses versioned universal article and dynamic-field contracts
71. KnowledgeArticlesModule.test.tsx — Knowledge Core first-class module creates a draft without caller-controlled tenant scope
72. KnowledgeArticlesModule.test.tsx — Knowledge Core first-class module hides authoring controls and shows a safe permission-scoped empty state
73. KnowledgeArticlesModule.test.tsx — Knowledge Core first-class module loads secured lifecycle details, revision evidence, and preserves favorites
74. KnowledgeCoreContract.test.ts — Knowledge Core wire contracts parses bounded question, feedback, and evidence-backed gap contracts
75. KnowledgeCoreContract.test.ts — Knowledge Core wire contracts parses lifecycle lists and server-derived capabilities
76. KnowledgeCoreContract.test.ts — Knowledge Core wire contracts parses permission-aware item details
77. KnowledgeCoreContract.test.ts — Knowledge Core wire contracts parses revisions, owners and collections
78. KnowledgeCoreContract.test.ts — Knowledge Core wire contracts rejects invalid lifecycle and identities
79. MailReaderContract.test.ts — Mail reader contract parses read and favorite mutations
80. MailReaderContract.test.ts — Mail reader contract parses secured account, list, and detail contracts
81. MailReaderContract.test.ts — Mail reader contract rejects malformed identities and nested data
82. MailReaderModule.test.tsx — Mail reader first-class module filters by account and does not send caller identity
83. MailReaderModule.test.tsx — Mail reader first-class module hides read-state mutation for a shared mailbox reader
84. MailReaderModule.test.tsx — Mail reader first-class module opens mail, marks it read, and renders body text without executable HTML
85. NotificationsContract.test.ts — Notifications module contracts fails closed on malformed identities, timestamps, states, and versions
86. NotificationsContract.test.ts — Notifications module contracts parses secured list, source-record detail, and mutation contracts
87. NotificationsModule.test.tsx — Notifications first-class module marks an opened item read and exposes secured source activity and favorites
88. NotificationsModule.test.tsx — Notifications first-class module uses only local search and unread inputs and can dismiss the current notification
89. PageRenderer.test.tsx — server-driven page renderer fails closed on malformed role simulation metadata
90. PageRenderer.test.tsx — server-driven page renderer fails closed when a block type was not authorized by the bootstrap
91. PageRenderer.test.tsx — server-driven page renderer fails closed when the manifest renderer key is not code-registered
92. PageRenderer.test.tsx — server-driven page renderer reconstructs validated flat parent relationships and renders each block once
93. PageRenderer.test.tsx — server-driven page renderer rejects invalid IDs, duplicate IDs, orphaned parents, and parent cycles
94. PageRenderer.test.tsx — server-driven page renderer renders authorized text as escaped React content with safe visual enums
95. PageRenderer.test.tsx — server-driven page renderer simulates presentation visibility without changing the canonical page
96. PageRenderer.test.tsx — server-driven page renderer uses bundled renderer keys and safe manifest defaults while ignoring moduleRef
97. PuckPageDesignerAdapter.test.ts — Puck page-designer adapter builds the Puck palette from the effective runtime component registry without changing canonical JSON
98. PuckPageDesignerAdapter.test.ts — Puck page-designer adapter fails closed before save when canonical or editor JSON is invalid
99. PuckPageDesignerAdapter.test.ts — Puck page-designer adapter keeps normal runtime rendering independent of either editor vendor
100. PuckPageDesignerAdapter.test.ts — Puck page-designer adapter keeps the Chai candidate as a bounded reference pass-through, not a production adapter
101. PuckPageDesignerAdapter.test.ts — Puck page-designer adapter persists controlled edits while retaining bindings, actions, responsive rules, and security metadata
102. PuckPageDesignerAdapter.test.ts — Puck page-designer adapter renders the round-tripped proof through the normal server-driven runtime
103. PuckPageDesignerAdapter.test.ts — Puck page-designer adapter selects one pinned launch editor and losslessly round-trips the canonical proof
104. RecordActivityContract.test.ts — Record activity contract parses secured search and sanitized activity data
105. RecordActivityContract.test.ts — Record activity contract rejects malformed identities and nested collections
106. RecordActivityContract.test.ts — Record activity contract requires bounded contract types and object details
107. RecordActivityModule.test.tsx — Record activity first-class module applies event and UTC date filters without caller identity
108. RecordActivityModule.test.tsx — Record activity first-class module opens the secured timeline and toggles its favorite
109. RecordActivityModule.test.tsx — Record activity first-class module requests the next bounded timeline page
110. RecordGraphContract.test.ts — Record graph contract parses add and remove results
111. RecordGraphContract.test.ts — Record graph contract parses independently secured related and contextual knowledge
112. RecordGraphContract.test.ts — Record graph contract parses secured search and graph responses
113. RecordGraphContract.test.ts — Record graph contract rejects malformed identities and nested collections
114. RecordGraphModule.test.tsx — Record graph first-class module adds an editable relation using canonical record and relation keys
115. RecordGraphModule.test.tsx — Record graph first-class module does not expose deletion when either endpoint is read-only
116. RecordGraphModule.test.tsx — Record graph first-class module opens a bounded secured graph and toggles its favorite
117. RelatedKnowledgePanel.test.tsx — Related Knowledge panel renders only the secured related response
118. ReservationsModule.test.tsx — ReservationsModule loads secured reservations and opens payment-aware detail
119. ReservationsModule.test.tsx — ReservationsModule shows protected payment references without raw card fields
120. RoleSimulation.test.tsx — developer/admin role simulation previews presentation roles but loads data with the unchanged real-user API
121. RuntimeAssetManager.test.tsx — RuntimeAssetManager keeps shared assets read-only for non-managers
122. RuntimeAssetManager.test.tsx — RuntimeAssetManager lists authorized assets without exposing tenant or storage routing
123. RuntimeAssetManager.test.tsx — RuntimeAssetManager uploads and removes tenant-owned assets only when the server grants management
124. RuntimeDocumentMetadata.test.tsx — runtime document metadata emits public title, description, robots, and same-origin canonical metadata
125. RuntimeDocumentMetadata.test.tsx — runtime document metadata keeps private pages out of indexes and suppresses canonical/description output
126. RuntimeDocumentMetadata.test.tsx — runtime document metadata replaces route metadata and rejects off-origin canonical targets
127. SaasDesignStudio.test.tsx — in-SaaS Design studio makes duplication explicit and opens Puck before the Monaco advanced view
128. SaasDesignStudio.test.tsx — in-SaaS Design studio protects unsaved menu changes before leaving Design mode
129. SaasDesignStudio.test.tsx — in-SaaS Design studio reuses the exact shared PageKey when Add existing is saved to another User Type menu
130. TenantAssetsContract.test.ts — tenant asset contract accepts bounded secured runtime URLs
131. TenantAssetsContract.test.ts — tenant asset contract rejects active and duplicate asset identities
132. WebLinksContract.test.ts — Web links module contracts parses versioned universal records, capabilities, and dynamic fields
133. WebLinksContract.test.ts — Web links module contracts rejects unsafe URLs, malformed identities, timestamps, and versions
134. WebLinksModule.test.tsx — Web links first-class module creates a link without caller-controlled tenant scope
135. WebLinksModule.test.tsx — Web links first-class module hides authoring controls from readers
136. WebLinksModule.test.tsx — Web links first-class module loads secured detail with a hardened external link and universal features
137. WorkOrdersContract.test.ts — Work Orders contracts fails closed on malformed identities, statuses, and versions
138. WorkOrdersContract.test.ts — Work Orders contracts parses lifecycle, assignment, and universal-record identities
139. WorkOrdersModule.test.tsx — Work Orders first-class module creates without caller-controlled tenant scope
140. WorkOrdersModule.test.tsx — Work Orders first-class module loads secured lifecycle detail and changes status with concurrency
141. api.test.ts — tenant runtime API loads a binding by key without caller-controlled identity or operation
142. api.test.ts — tenant runtime API loads a configured slug without sending caller-controlled tenant scope
143. api.test.ts — tenant runtime API loads only a page-key target and rejects malformed presentation JSON
144. api.test.ts — tenant runtime API logs in without caller-controlled SaaS scope
145. api.test.ts — tenant runtime API rejects a component manifest that names an unsafe renderer
146. api.test.ts — tenant runtime API rejects malformed and mismatched binding contracts
147. api.test.ts — tenant runtime API submits form values through the authenticated page route without caller scope
148. api.test.ts — tenant runtime API uses authenticated Calendar routes without caller-controlled scope
149. api.test.ts — tenant runtime API uses authenticated Contacts routes without caller-controlled scope
150. api.test.ts — tenant runtime API uses authenticated Files routes while keeping storage and tenant scope server-owned
151. designApi.test.ts — in-SaaS Design API makes duplication explicit and fails closed without a Design session
152. designApi.test.ts — in-SaaS Design API uses the short-lived builder bearer session without browser-owned database scope
153. pageAdoption.test.ts — tenant page adoption loads three-way evidence and explicitly applies or undoes without client scope
154. pageAdoption.test.ts — tenant page adoption rejects an unsafe page before requesting adoption evidence
155. pageAdoption.test.ts — tenant page adoption rejects non-drift and malformed presentation evidence
156. pageEditLock.test.ts — tenant page edit lock acquires, renews, and releases only the server-scoped page lease
157. pageEditLock.test.ts — tenant page edit lock rejects an unsafe page target before lock acquisition
158. pageEditLock.test.ts — tenant page edit lock renews halfway through a valid lease and rejects incomplete leases
159. pageEditLock.test.ts — tenant page edit lock represents a conflicting editor without exposing their identity
160. pagePublicationLifecycle.test.ts — page publication lifecycle advances exactly one runtime version and consumes the published draft
161. pagePublicationLifecycle.test.ts — page publication lifecycle keeps the runtime version unchanged while a draft is saved
162. pagePublicationLifecycle.test.ts — page publication lifecycle marks a draft based on an old runtime version as stale
163. pagePublicationLifecycle.test.ts — page publication lifecycle rejects a publish acknowledgement for a different snapshot
164. pagePublicationLifecycle.test.ts — page publication lifecycle rejects skipped or replayed runtime versions
165. pageRevisions.test.ts — tenant page revisions preserves server validation failures as a non-published save report
166. pageRevisions.test.ts — tenant page revisions rejects malformed historical presentation JSON before an editor can load it
167. pageRevisions.test.ts — tenant page revisions rejects unsafe page and revision identifiers before a request
168. pageRevisions.test.ts — tenant page revisions uses authenticated page targets without caller-controlled tenant scope
169. pageValidation.test.ts — canonical page document validation accepts one valid vendor-neutral document for save, publish, and runtime
170. pageValidation.test.ts — canonical page document validation allows warning-bearing drafts but never allows them to publish
171. pageValidation.test.ts — canonical page document validation blocks parent cycles and documents deeper than the runtime bound
172. pageValidation.test.ts — canonical page document validation never publishes an invalid first-class form definition
173. pageValidation.test.ts — canonical page document validation rejects malformed envelopes and invalid block identities
174. pageValidation.test.ts — canonical page document validation rejects the same malformed nested structures that runtime rejects
175. pageValidation.test.ts — canonical page document validation reports removed merge anchors against the prior document
176. puckCssSecurity.test.ts — Puck CSS production security removes the external font import while preserving editor styles
177. puckCssSecurity.test.ts — Puck CSS production security targets only the pinned Puck distribution stylesheet
178. router.test.ts — runtime browser routing maps encoded pathnames and language targets without accepting traversal
179. router.test.ts — runtime browser routing uses a validated page-key history fallback for shell navigation
180. useRuntimeDataBinding.test.tsx — runtime data binding hook does not call the gateway for an unbound block
181. useRuntimeDataBinding.test.tsx — runtime data binding hook loads an approved key and exposes only the returned data
182. webSecurity.test.ts — web security request proof adds proof only to unsafe requests
183. webSecurity.test.ts — web security request proof creates and reuses a host-scoped CSRF token
184. webSecurity.test.ts — web security request proof does not overwrite an unrelated authorization header

**Universal Inbox UI — 46 passed**
1. ContextualItemDetail.test.tsx — ContextualItemDetail maps AiActionApproval to its approval renderer
2. ContextualItemDetail.test.tsx — ContextualItemDetail maps AiInsight to its ai-alert renderer
3. ContextualItemDetail.test.tsx — ContextualItemDetail maps Conversation to its message renderer
4. ContextualItemDetail.test.tsx — ContextualItemDetail maps CustomWebhook to its generic renderer
5. ContextualItemDetail.test.tsx — ContextualItemDetail maps PageFormSubmission to its form renderer
6. ContextualItemDetail.test.tsx — ContextualItemDetail maps PaymentEvent to its payment renderer
7. ContextualItemDetail.test.tsx — ContextualItemDetail renders only the secured projection and directs users to the canonical source
8. DeliveryDebugPanel.test.tsx — DeliveryDebugPanel shows safe failure fields and retries only authorized rows
9. GoClawApprovalQueue.test.tsx — GoClawApprovalQueue fails closed and clears review content when loading fails
10. GoClawApprovalQueue.test.tsx — GoClawApprovalQueue makes a stale ActivityVersion fence prominent
11. GoClawApprovalQueue.test.tsx — GoClawApprovalQueue shows summary, secured context, draft, actions, risk, confidence, and lineage
12. GoClawApprovalQueue.test.tsx — GoClawApprovalQueue submits only changed action input with reviewer notes and refreshes
13. InboxHumanStateControls.test.tsx — InboxHumanStateControls offers reopen for terminal work
14. InboxHumanStateControls.test.tsx — InboxHumanStateControls uses only InboxItem identity for read, assignment, priority, waiting, snooze, resolve and close
15. UniversalInbox.test.tsx — UniversalInbox maps views to secured queue filters instead of client-side identity filters
16. UniversalInbox.test.tsx — UniversalInbox removes queue content and shows a safe error when secured loading fails
17. UniversalInbox.test.tsx — UniversalInbox renders views, InboxItem queue, and generic source detail as three panes
18. UniversalInboxBell.test.tsx — UniversalInboxBell opens the Universal Inbox by InboxItemId, never ConversationId
19. UniversalInboxBell.test.tsx — UniversalInboxBell refreshes the secured badge when inbox activity announces a change
20. UniversalInboxBell.test.tsx — UniversalInboxBell surfaces approval, human-review, and GoClaw-working states
21. WorkflowApprovalControls.test.tsx — WorkflowApprovalControls approves using only Inbox identity and the current activity fence
22. WorkflowApprovalControls.test.tsx — WorkflowApprovalControls does not render decisions for non-workflow approval items
23. WorkflowApprovalControls.test.tsx — WorkflowApprovalControls shows a safe failure and remains available for retry
24. approvalClient.test.ts — approval queue HTTP client posts reviewer edits without accepting identity fields
25. approvalClient.test.ts — approval queue HTTP client rejects cross-origin configuration and unbounded row requests
26. approvalClient.test.ts — approval queue HTTP client uses fixed same-origin disposition routes
27. approvalClient.test.ts — approval queue HTTP client uses only the secured same-origin GET and sends no caller identity
28. approvalContracts.test.ts — approval queue contracts parses canonical batches, draft JSON, actions, and activity lineage
29. approvalContracts.test.ts — approval queue contracts rejects duplicate batch and suggestion lineage
30. approvalContracts.test.ts — approval queue contracts rejects inconsistent stale fences before rendering
31. client.test.ts — Universal Inbox HTTP client loads badge and notifications through fixed same-origin paths
32. client.test.ts — Universal Inbox HTTP client rejects cross-origin API configuration
33. client.test.ts — Universal Inbox HTTP client sends a version-fenced workflow decision without tenant identity
34. client.test.ts — Universal Inbox HTTP client sends one bounded human-state mutation without tenant identity
35. client.test.ts — Universal Inbox HTTP client uses only same-origin secured item endpoints and never sends tenant identity query parameters
36. client.test.ts — Universal Inbox HTTP client verifies detail identity against the requested InboxItem
37. contracts.test.ts — Universal Inbox contracts derives a breached SLA presentation from the secured due time
38. contracts.test.ts — Universal Inbox contracts fails closed when detail identity differs from the selected item
39. contracts.test.ts — Universal Inbox contracts normalizes a service detail envelope while retaining source identity
40. contracts.test.ts — Universal Inbox contracts normalizes omitted zero badge aggregates and preserves attention counts
41. contracts.test.ts — Universal Inbox contracts parses a stable support-ticket reference
42. contracts.test.ts — Universal Inbox contracts parses notification InboxItem identities and rejects duplicates
43. contracts.test.ts — Universal Inbox contracts parses owner-managed email ticketing settings and validates mutation identity
44. contracts.test.ts — Universal Inbox contracts parses typed InboxItem queue rows
45. contracts.test.ts — Universal Inbox contracts rejects duplicate InboxItem pointers
46. contracts.test.ts — Universal Inbox contracts rejects invalid status values before rendering

**End-to-end launch proofs — 65 passed**
1. tests.e2e.test_ai_rag_proof.AiRagProofContractTests.test_every_database_contract_exists_in_current_exports
2. tests.e2e.test_ai_rag_proof.AiRagProofContractTests.test_implementations_and_evidence_are_present
3. tests.e2e.test_ai_rag_proof.AiRagProofContractTests.test_journey_order_is_fixed
4. tests.e2e.test_ai_rag_proof.AiRagProofContractTests.test_qwen_profile_preserves_canonical_graph_and_dimensions
5. tests.e2e.test_ai_rag_proof.AiRagProofContractTests.test_repeatability_rollback_and_physical_boundary_are_explicit
6. tests.e2e.test_ai_rag_proof.AiRagProofContractTests.test_security_order_is_explicit
7. tests.e2e.test_appliance_proof.ApplianceProofContractTests.test_all_implementations_evidence_runner_and_runbook_exist
8. tests.e2e.test_appliance_proof.ApplianceProofContractTests.test_catalog_is_available_but_not_a_startup_dependency
9. tests.e2e.test_appliance_proof.ApplianceProofContractTests.test_field_service_closes_over_local_runtime
10. tests.e2e.test_appliance_proof.ApplianceProofContractTests.test_five_operational_planes_are_local_and_template_library_is_central
11. tests.e2e.test_appliance_proof.ApplianceProofContractTests.test_journey_order_is_fixed
12. tests.e2e.test_appliance_proof.ApplianceProofContractTests.test_runtime_claim_is_firecracker_systemd_and_honest
13. tests.e2e.test_appliance_proof.ApplianceProofContractTests.test_sovereignty_and_outage_preserve_local_runtime
14. tests.e2e.test_communications_proof.CommunicationsProofContractTests.test_authorization_fences_and_external_secrets_are_explicit
15. tests.e2e.test_communications_proof.CommunicationsProofContractTests.test_deterministic_provider_fixture_uses_stable_external_secret_contract
16. tests.e2e.test_communications_proof.CommunicationsProofContractTests.test_every_database_contract_exists_in_current_exports
17. tests.e2e.test_communications_proof.CommunicationsProofContractTests.test_implementations_and_evidence_are_present
18. tests.e2e.test_communications_proof.CommunicationsProofContractTests.test_journey_order_is_fixed
19. tests.e2e.test_communications_proof.CommunicationsProofContractTests.test_repeatability_and_rollback_are_explicit
20. tests.e2e.test_custom_data_proof.CustomDataProofContractTests.test_authoring_and_runtime_authority_are_separated
21. tests.e2e.test_custom_data_proof.CustomDataProofContractTests.test_complete_journey_order_is_fixed
22. tests.e2e.test_custom_data_proof.CustomDataProofContractTests.test_every_database_contract_exists_in_current_exports
23. tests.e2e.test_custom_data_proof.CustomDataProofContractTests.test_implementations_and_evidence_are_present
24. tests.e2e.test_custom_data_proof.CustomDataProofContractTests.test_repeatability_and_cross_database_rollback_are_explicit
25. tests.e2e.test_goclaw_approval_proof.GoClawApprovalProofContractTests.test_every_database_contract_exists_in_current_exports
26. tests.e2e.test_goclaw_approval_proof.GoClawApprovalProofContractTests.test_implementations_and_evidence_are_present
27. tests.e2e.test_goclaw_approval_proof.GoClawApprovalProofContractTests.test_journey_order_is_fixed
28. tests.e2e.test_goclaw_approval_proof.GoClawApprovalProofContractTests.test_physical_environment_claims_are_excluded
29. tests.e2e.test_goclaw_approval_proof.GoClawApprovalProofContractTests.test_repeatability_and_rollback_are_explicit
30. tests.e2e.test_goclaw_approval_proof.GoClawApprovalProofContractTests.test_server_scope_and_fences_are_explicit
31. tests.e2e.test_installable_service_proof.InstallableServiceProofContractTests.test_authorization_and_exact_artifact_fences_are_explicit
32. tests.e2e.test_installable_service_proof.InstallableServiceProofContractTests.test_every_database_contract_exists_in_current_exports
33. tests.e2e.test_installable_service_proof.InstallableServiceProofContractTests.test_firecracker_boundary_is_honest_and_docker_free_in_production
34. tests.e2e.test_installable_service_proof.InstallableServiceProofContractTests.test_implementations_and_evidence_are_present
35. tests.e2e.test_installable_service_proof.InstallableServiceProofContractTests.test_journey_order_is_fixed
36. tests.e2e.test_installable_service_proof.InstallableServiceProofContractTests.test_proof_does_not_hide_separate_worker_host_work
37. tests.e2e.test_installable_service_proof.InstallableServiceProofContractTests.test_repeatability_rollback_and_targets_are_explicit
38. tests.e2e.test_marketplace_snapshot_proof.MarketplaceSnapshotProofContractTests.test_authorization_and_exact_version_fences_are_explicit
39. tests.e2e.test_marketplace_snapshot_proof.MarketplaceSnapshotProofContractTests.test_every_database_contract_exists_in_current_exports
40. tests.e2e.test_marketplace_snapshot_proof.MarketplaceSnapshotProofContractTests.test_implementations_and_evidence_are_present
41. tests.e2e.test_marketplace_snapshot_proof.MarketplaceSnapshotProofContractTests.test_journey_order_is_fixed
42. tests.e2e.test_marketplace_snapshot_proof.MarketplaceSnapshotProofContractTests.test_real_payment_is_not_claimed
43. tests.e2e.test_marketplace_snapshot_proof.MarketplaceSnapshotProofContractTests.test_repeatability_and_rollback_are_explicit
44. tests.e2e.test_new_saas_proof.NewSaasProofContractTests.test_complete_journey_order_is_fixed
45. tests.e2e.test_new_saas_proof.NewSaasProofContractTests.test_every_database_contract_exists_in_current_exports
46. tests.e2e.test_new_saas_proof.NewSaasProofContractTests.test_implementations_and_evidence_are_present
47. tests.e2e.test_new_saas_proof.NewSaasProofContractTests.test_repeatability_and_rollback_are_explicit
48. tests.e2e.test_snowflake_proof.SnowflakeProofContractTests.test_every_database_contract_exists_in_current_exports
49. tests.e2e.test_snowflake_proof.SnowflakeProofContractTests.test_field_service_fixture_covers_all_manifest_datasets_and_failure_safety
50. tests.e2e.test_snowflake_proof.SnowflakeProofContractTests.test_implementations_evidence_runner_and_runbook_exist
51. tests.e2e.test_snowflake_proof.SnowflakeProofContractTests.test_journey_order_is_fixed
52. tests.e2e.test_snowflake_proof.SnowflakeProofContractTests.test_provider_and_runtime_claims_are_honest
53. tests.e2e.test_snowflake_proof.SnowflakeProofContractTests.test_rollback_and_target_contract_are_explicit
54. tests.e2e.test_snowflake_proof.SnowflakeProofContractTests.test_server_scope_and_role_isolation_are_explicit
55. tests.e2e.test_support_dogfood_proof.SupportDogfoodProofTests.test_static_proof_is_exact_version_and_customer_safe
56. tests.e2e.test_visual_build_proof.VisualBuildProofContractTests.test_canonical_fixture_carries_module_binding_and_role_metadata
57. tests.e2e.test_visual_build_proof.VisualBuildProofContractTests.test_complete_journey_order_is_fixed
58. tests.e2e.test_visual_build_proof.VisualBuildProofContractTests.test_every_database_contract_exists_in_current_exports
59. tests.e2e.test_visual_build_proof.VisualBuildProofContractTests.test_implementations_and_evidence_are_present
60. tests.e2e.test_visual_build_proof.VisualBuildProofContractTests.test_repeatability_authorization_and_rollback_are_explicit
61. tests.e2e.test_workflow_proof.WorkflowProofContractTests.test_authorization_and_approval_fences_are_explicit
62. tests.e2e.test_workflow_proof.WorkflowProofContractTests.test_every_database_contract_exists_in_current_exports
63. tests.e2e.test_workflow_proof.WorkflowProofContractTests.test_implementations_and_evidence_are_present
64. tests.e2e.test_workflow_proof.WorkflowProofContractTests.test_journey_order_is_fixed
65. tests.e2e.test_workflow_proof.WorkflowProofContractTests.test_repeatability_and_rollback_are_explicit

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/trust/battle-test-2026-08-30.html).

---
title: "Battle test: five million records, exact counts, and a faster Inbox badge"
section: "Trust & Security"
canonical_url: "https://support.buildwithhq.com/trust/battle-test-five-million-row-2026-09-23.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Battle test: five million records, exact counts, and a faster Inbox badge

What we measured while tuning secured Contacts, Global Search, and Universal Inbox paths on a five-million-record database.

## In brief

- **Scale fixture:** 5,000,000 records across 20 organizations
- **Authenticated soak:** 10,851 requests; zero errors or pool waiters
- **Security result:** Tenant, role, and location checks passed

On September 23, 2026, we used a retained five-million-record Core database to test the paths most likely to become expensive as a SaaS grows: authorized Contacts counts, Global Search counts, and the Universal Inbox attention badge. We tested both the large database directly and a rebuilt authenticated API gateway. The work also updated the golden Core database so newly provisioned SaaS databases inherit the reviewed procedures and indexes.

Note

These are measurements from one controlled local test machine, not an availability guarantee or customer SLA. The large-scale SQL fixture and the authenticated gateway fixture are deliberately separate; we do not present a small routed database as five-million-row HTTP evidence.

## The test shape

- Five million active records distributed across 20 tenant organizations.
- About 250,000 Contacts and 250,000 open Inbox items in each loaded organization used by the scale cases.
- Real DataRoles, location assignments, direct-conversation visibility, read state, and server-derived tenant/user identity.
- A second 400-contact fixture to catch plans that help a very large organization but penalize the more common small organization.
- Concurrency at 8 and 32, followed by a 60-second authenticated mixed gateway run.

## What changed

Exact totals remain opt-in. Ordinary Contacts and Global Search requests return rows first without calculating a full count. The product asks for the exact authorized count separately and caches it for the session. Browsing is bounded to 5,000 matches, while the exact total can still report all authorized matches. Search runs before the browse limit, so a person can find a contact outside the unfiltered window.

The exact Contacts and Search counts use dedicated secured procedures and indexes rather than copying the entire authorized set into a temporary primary-key table. The common Global Search path starts from indexed terms and intersects terms before applying the same record-security checks.

The top navigation no longer calculates the complete per-source Inbox aggregate every time it refreshes. It performs a fixed-work probe that displays 1 through 98 or **99+**. Opening Universal Inbox separately loads the exact unread, approval, human-review, worker, assignment, delivery, and per-source totals. A failed exact request is shown as unavailable; it is never converted into a false zero.

## Large-database results

| Case | Before | After |
| --- | --- | --- |
| Contacts exact count (249,998 visible) | 2,786,694 mean logical reads; 4.525 s p95 | 5,092 mean logical reads; 1.234 s p95 |
| Global Search common-term exact count (250,000 visible) | 1,506,553 mean logical reads; 2.581 s p95 | 7,328 mean logical reads; 0.888 s p95 |
| Top-bar Inbox attention | Exact aggregation: 7,416 logical reads; 1.070 s p95 | Bounded 99+ probe: 3,210 logical reads; 0.510 s p95 |

The optimized Contacts plan reduced logical reads by more than 99% in this fixture. It did not make exact counting free: an exact count still has to prove every visible match. That is why exact totals remain opt-in and session-cached instead of running on every list request.

## Concurrency and connection pools

At direct-SQL concurrency 32, the bounded badge completed 64/64 operations with a 1.184 s p95 and 30.4 operations per second. The exact badge also completed 64/64, but its p95 was 2.249 s and throughput was 15.7 operations per second. The bounded projection therefore protects the high-frequency top-bar path while retaining exact totals where they are useful.

The authenticated gateway then mixed the bounded badge, exact badge, fast Contacts, and fast Global Search at concurrency 32 for 60 seconds. All 10,851 requests returned HTTP 200, with no errors or timeouts. Throughput was 180.4 operations per second. Process-level SqlClient counters observed six active pools, at most 59 managed connections, at most 22 active connections, and zero connections waiting for a pool slot. An independent SQL-session observer saw at most 59 gateway sessions and 24 running sessions.

| Authenticated route | p95 | p99 |
| --- | --- | --- |
| Bounded Inbox badge | 275 ms | 433 ms |
| Fast Contacts page | 281 ms | 439 ms |
| Exact Inbox badge | 371 ms | 505 ms |
| Fast Global Search page | 241 ms | 606 ms |

This is intentionally a capacity test, so a test-only high rate limit was bound to the one disposable SaaS. Production rate-limit defaults were not changed, and normal 429/Retry-After behavior remains covered separately.

## Security and correctness checks

Count and badge performance is not allowed to weaken authorization. Independent derivations compared the optimized results with the established secured-record envelope. The suite covered six role/location identities across organizations, including users with no visible location and users allowed to see the loaded location. A hostile request targeting another organization returned no information, and a forged SaaS identifier through the authenticated gateway returned HTTP 403.

The migration was replayed twice, its grants and index were inspected, and procedure contracts were regenerated. Stored-procedure conformance reported zero violations and zero unresolved changed calls. Before applying to golden and the routed battle Core, the operator created compressed COPY_ONLY backups with CHECKSUM and passed RESTORE VERIFYONLY. The routed activation gate then confirmed that the sole active Core had the required procedure and index contract.

## What this does not claim

- The five-million-row plan measurements are direct SQL evidence; the authenticated HTTP soak used the current smaller routed battle tenant.
- The observed latency belongs to this hardware, data distribution, and concurrent workload. A different workload can produce different plans and timings.
- Instance-wide SQL wait deltas can include unrelated local activity.
- This test is not a disaster-recovery exercise, third-party-provider certification, public Internet load test, or compliance attestation.

## Design guidance for builders and API clients

- Use the default rows-first Contacts and Global Search calls for interactive pages.
- Request an exact count only when the user needs it, and cache it for the session or invalidate it after a relevant write.
- Treat `99+` as an attention indicator, not an exact total. Load the exact Inbox badge when the Inbox panel opens.
- Do not treat `hasMore: false` at the 5,000 browse boundary as proof that a full export is complete. Use the documented uncapped Records enumeration path for complete synchronization.

Related guidance: [Progressive loading and exact counts](../api/progressive-loading-and-counts.html)  and [Tenant Data Security](tenant-data-security.html).

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/trust/battle-test-five-million-row-2026-09-23.html).

---
title: "Data lifecycle, residency, and portability"
section: "Trust & Security"
canonical_url: "https://support.buildwithhq.com/trust/data-lifecycle.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Data lifecycle, residency, and portability

How customer data is isolated, exported, backed up to customer-owned storage, and assigned to an enterprise deployment.

## In brief

- **Database boundary:** One SaaS application
- **Organization boundary:** Server-enforced account permissions
- **Portability:** Deployment-specific

## SaaS databases and customer organizations

Each SaaS application has its own core, AI, and logs databases. Customer organizations inside that app are tenant accounts (AppAccounts); they do not each receive another database set. Server-verified account identity, DataRoles, Locations, and record permissions keep organizations separated within the app.

An organization export must include only that account's authorized data. A full application database backup is a different operation and can contain multiple organizations; it must never be handed to an individual organization as its account export. See [Tenant Data Security](tenant-data-security.html)  for the permission model.

## Export at any time

The account owner can run an export whenever needed: for a backup, an audit, analysis in another system, migration work, or to build an independent replacement system. The export includes customer records, files, AI data, operational history, and audit history, plus a manifest and checksums used to verify completeness. See [Back up and download your data](../end-user/download-your-data.html).

## Customer-owned backup storage

Customers can keep restore bundles in their own Amazon S3 storage. A bundle can contain the customer database, uploaded files, application schemas and settings, a machine-readable manifest, and checksums. The destination remains under the customer's control, including bucket access, retention, versioning, and Object Lock when the customer enables it.

BuildWithHQ uses limited backup-only access for delivery to the selected bucket. The backup destination is not treated as a general-purpose BuildWithHQ storage account, and BuildWithHQ does not rely on the customer sharing an interactive cloud login.

## Residency and enterprise deployment

For enterprise customers, BuildWithHQ workloads can be placed in an agreed AWS or Azure environment, including a customer-approved cloud or virtual-machine deployment. The selected region, operating responsibilities, retention requirements, and recovery objectives are recorded in the enterprise order and operating plan so they can be reviewed before deployment.

Note

Residency, deletion windows, retention periods, RPO, and RTO can vary by deployment. BuildWithHQ documents the values that apply to the customer's environment in the applicable service terms or enterprise operating plan rather than implying one unpublished number applies everywhere.

## Cancellation and deletion

Before closing an account, the owner can run a current export and verify its checksums. Cancellation stops future renewal at the end of the paid period; the retention and deletion schedule that applies afterward is the schedule stated in the customer's service terms or enterprise agreement. A customer should not depend on a post-cancellation recovery window as its backup plan.

## If BuildWithHQ shuts down

The continuity plan is designed to preserve more than raw data. BuildWithHQ will release the managed API code and the JSON interpreter needed to run exported application definitions. A customer application can then be restored in a cloud environment or on a virtual machine using that customer's isolated database, files, schemas, settings, and application definitions. See [Business continuity and application portability](business-continuity-and-portability.html)  for the complete recovery model.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/trust/data-lifecycle.html).

---
title: "Business continuity and application portability"
section: "Trust & Security"
canonical_url: "https://support.buildwithhq.com/trust/business-continuity-and-portability.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Business continuity and application portability

How applications can relocate to AWS or Azure, or be restored in a cloud or virtual machine if BuildWithHQ shuts down.

## In brief

- **Enterprise option:** Relocate to AWS or Azure
- **Shutdown option:** Run in a cloud or virtual machine
- **Recovery unit:** One isolated customer at a time

## Two reasons to relocate

The same portability model supports two distinct situations:

- **Enterprise deployment:** while BuildWithHQ is operating, an enterprise customer can arrange for its workload to run in an agreed AWS or Azure environment, including a customer-approved virtual-machine architecture.
- **Company shutdown:** if BuildWithHQ ceases operation, customers can restore their applications to a cloud environment or virtual machine using their exported application definitions, isolated data, files, and the released continuity runtime.

## What can be carried forward

- **Application definition:** versioned JSON documents and JSON Schema contracts for pages, components, approved bindings, workflows, and related configuration.
- **Customer database:** the customer's records, AI data, operational history, and audit history from that customer's isolated database.
- **Files:** uploaded documents, images, attachments, and the metadata that connects them to records.
- **Restore metadata:** schemas, settings, manifests, versions, and checksums needed to inventory and validate the package.
- **Continuity runtime:** the managed API code and JSON interpreter needed to execute the exported application definitions if BuildWithHQ shuts down.

## Why the database boundary matters

Customer data is not mixed with other customers in shared application tables. Each customer has its own database and audit history. That means a recovery team can restore one customer from its own package without first extracting that customer from a multi-customer data store. The same boundary also makes it practical for different customers to choose different recovery hosts.

## Customer-owned restore bundles

A customer can direct restore bundles to customer-owned Amazon S3 storage. The customer controls the bucket, region, access, retention, versioning, and optional Object Lock. Each bundle includes a machine-readable manifest and checksums so the package can be inventoried and checked before a restore begins.

Tip

Keep periodic restore bundles in storage your organization controls and test the checksums. Portability is strongest when the latest usable copy already exists outside the platform.

## Shutdown continuity release

If BuildWithHQ ceases operation, BuildWithHQ will release the managed API code and JSON interpreter required to run exported BuildWithHQ application definitions. The resulting system can run in a cloud environment or on a virtual machine. The objective is to let each customer bring its own application back online with its own hosting instead of receiving only raw data and starting a complete rebuild.

## Recovery sequence

1. Choose the target AWS, Azure, other cloud, or virtual-machine environment.
2. Verify the restore bundle against its manifest and checksums.
3. Restore the customer's isolated database and uploaded files.
4. Load the exported page, workflow, schema, and settings definitions.
5. Deploy the managed API code and JSON interpreter supplied through the continuity release.
6. Recreate credentials and third-party connections; secrets are deliberately excluded from exports.
7. Validate the application, then move the customer's domain or traffic to the restored environment.

## What portability does not silently assume

Exports do not include usable passwords, API keys, OAuth tokens, or other live credentials. Third-party accounts, cloud tenancy, DNS control, and licenses for external services remain with their respective owners. Exact residency, retention, RPO, RTO, and operating-responsibility commitments are recorded in the applicable service terms or enterprise operating plan.

## Related documentation

- [Data lifecycle, residency, and portability](data-lifecycle.html)
- [Back up and download your data](../end-user/download-your-data.html)
- [Application definitions and advanced JSON mode](../builder-guide/raw-json-mode.html)
- [Tenant Data Security](tenant-data-security.html)

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/trust/business-continuity-and-portability.html).

---

# Section: Operations runbooks

---
title: "Core service crash-loop response"
section: "Operations runbooks"
canonical_url: "https://support.buildwithhq.com/runbooks/core-systemd-crash-loops.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Core service crash-loop response

How BuildWithHQ distinguishes controlled deployments from repeated automatic core-service restarts and routes the alert safely.

## In brief

- **Warning:** 2 automatic restarts in 15 minutes
- **High:** 4 automatic restarts in 15 minutes
- **Tenant workloads:** Monitored separately

BuildWithHQ monitors automatic systemd restarts for its API, authentication, control-plane, tenant-runtime, proxy, Harness, and release-bound worker services. The alert carries the exact service and unit instance needed by an operator, without tenant, user, database, credential, or correlation identifiers.

## What triggers the alert

The signal uses systemd's automatic `NRestarts` counter. A controlled deployment that stops one release and starts another does not increment that counter. Two automatic restarts within 15 minutes create a warning ticket; four or more create a high-severity page and ticket. The high condition replaces the warning condition for the same unit.

Tenant Firecracker workloads use a separate container-fleet signal and recovery path. A tenant workload identity cannot enter the core-service metric.

## First response

1. Confirm the core-systemd exporter is fresh. Missing telemetry is treated as a monitoring failure, not as proof that the service is healthy.
2. Use the alert's service, exact unit, unit instance, host scrape instance, and time window to inspect only the affected service.
3. Confirm the unit is running the expected signed release and that its dependencies and readiness endpoint are healthy.
4. Review secret-scrubbed service logs and authenticated traces for the alert interval. Correlation IDs stay in the protected trace system.
5. Use the health-gated deployment or worker lifecycle to roll forward or back. Do not edit live executables, environment files, leases, or database state to silence an alert.

## When the incident is resolved

Resolve the alert only after the exact unit remains stable for a complete 15-minute window, its readiness and dependent workflow checks pass, monitoring output is fresh, and both warning and high conditions clear. Public incident text should describe only the affected platform capability and recovery status; exact hosts, units, restart counts, correlations, and internal diagnostics remain private.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/runbooks/core-systemd-crash-loops.html).

---

# Section: Release Notes

---
title: "Release notes"
section: "Release Notes"
canonical_url: "https://support.buildwithhq.com/changelog/index-notes.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Release notes

Running log of platform releases.

## In brief

- **Cadence:** Posted with each release
- **Action items:** Flagged inline

## 2026.10.26 — Build pages from feature parts

New Fourteen features split into parts (header, filters, list, detail, form and more) that you place anywhere on a page. Contacts, Work Orders, Reservations, Calendar and Files can follow the record selected in another feature, so a customer page can show that customer's jobs, appointments, files and events. New work orders and reservations start linked to the followed contact. The Developer API list operations for those five features take `relatedRecordId`.

New Link types can be limited to two features, allow only one link, or be turned off, and each app can rename its features. See [Build pages from feature parts](../builder-guide/feature-parts.html).

## 2026.10.24 — Developer Kit 1.20.66: design and debug from your own tools

New The Developer API has 24 app design routes under `/v1/apps/{saasAppId}/design`: pages, authoring, custom fields and debug sessions, running on your app's own design code. Your builder keys act as the app owner: the draft key creates pages and edits drafts, the live key publishes and changes the live app. The CLI gains `bwhq page create|save`, `bwhq debug` and `bwhq design`; the SDK gains `BuildWithHQDesignClient`; the kit gains a drop-in `DeveloperDebugDrawer` React component. Debug sessions are shared with the owner's in-app drawer.

Changed The older `page-drafts` routes and the platform API's app debug sessions are removed; use the design routes. The kit changelog lists every contract change since 1.20.65.

## 2026.10.23 — Your app answers for itself

New Your app now asks the BuildWithHQ platform about itself only when someone signs in, and the Developer API checks each key with the platform at most once a day. Every other request is answered from your app's own database, which records each of those checks.

Improved Revoking or rotating a Developer API key, or binding it to a tenant user, takes effect on the key's next request. Suspending an app stops all of its keys on their next request.

Improved Page design, custom fields and authoring inside your app use one set of routes, `/api/runtime/design/*`, served by the app itself. The Builder Console no longer keeps its own copies of the custom-field and authoring routes. Developer API page, field and theme routes under `/v1/apps/{saasAppId}` are unchanged.

## 2026.10.22 — Current platform documentation

New guides explain explicit Personal, DataRole and Location choices, inherited child visibility, published pages, governed AI actions, headless and MCP access, integration readiness and safe + Debug support evidence. Onboarding distinguishes app creation from provisioning readiness. Secure-field guidance identifies supported Contact reveal flows. Public API downloads retain the exact verified Developer Kit contract; working API changes require a separate kit release.

## 2026.10.16 — Developer Kit 1.20.70

Includes 129 Builder Platform operations, bounded Chat, Conversation and Discussion history, board topic paging, and updated nullable fields, opaque revisions and Company News errors. The exact archive passed the release gate and the public gateway passed authenticated read-contract checks. [Read the release notes and remaining contract warnings](../api/current-api-contracts.html#developer-kit-12061).

## 2026.10.16 — Developer Kit 1.20.60

Preserves exact revision strings, aligns scopes and error declarations, and validates the extracted archive through the release gate. Matching server changes still require deployment and live verification. [Read the release notes](../api/current-api-contracts.html#developer-kit-12060).

Note

Major platform updates are listed newest first. Use View next 10 for older entries; without JavaScript, every entry remains readable on this page.

## 2026.09.22 - Developer Kit 1.20.13 publication and enumeration safeguards

Improved Kit publication now requires fresh authenticated checks of the actual public count endpoints and fast defaults, plus all routed core procedure contracts. The marketplace operation total is generated from the kit statistics. The README and changelog explicitly identify the 1.20.12 bounded-list behavior change and document the existing uncapped generic Records enumeration API, native contact hydration and concurrent-write limits. The kit includes an executable iterator that reports incomplete runs rather than silently treating a page budget as success. No new API operation or database migration is introduced. [Read the migration guidance](../api/progressive-loading-and-counts.html).

## 2026.09.22 - Fast rows, full secured counts, and Developer Kit 1.20.12

New Contacts and Global Search now default to fast rows with optional separate exact-count endpoints. Interactive browsing covers up to 5,000 matching records; the authorized count remains uncapped. Search is applied before the browsing limit, so more-specific searches can find records outside an unfiltered browse window. This supersedes the older full-directory paging policy. Native pages progressively show rows and later fill in counts; these are separate JSON responses, not a new SSE or NDJSON list transport. The kit includes a tested progressive Contacts SDK example, generated count operations and read scopes. The new guide covers cancellation, count freshness, tenant isolation and enterprise release/restore evidence. [Read the integration guide](../api/progressive-loading-and-counts.html).

## 2026.09.18 - One Developer Kit with account overlay sync

New Developer Kit 1.20.4 is the single canonical BuildWithHQ / API43 download. Its new standard-library sync command securely downloads, verifies, and expands the signed-in account’s current pages, bindings, presentation, compatibility and Lego contracts into the same workspace. Separate draft and live API credentials remain in trusted server secret storage, while account export continues to require the short-lived tenant owner session. The existing direct Admin ZIP download and every previous SDK/API capability remain available.

## 2026.09.15 - Developer Kit 1.20.3 live connector verification

Fixed The shipped TypeScript connector was compiled from the public ZIP and exercised with disposable live-app and read-only credentials against the million-record local tenant. Organization listing exposed and drove a fix for an API service that incorrectly supplied the planner-owned correlation parameter to organization procedures. The battle credential now includes the current marketplace, asset, and theme scopes. After correction, 23 SDK workflows, all 199 authenticated module-route registration checks, 24 module representative reads, 40 gateway-family cases, 95 gateway unit tests, 18 kit examples, and 19 post-run database integrity checks passed. All disposable credentials and the temporary SQL principal were revoked and removed. This is local integration evidence, not public-production or external-provider certification.

## 2026.09.15 - Builder staged database inventory and guarded executor

Added The Builder Backups page displays an operator-published, app-scoped database inventory with Ready, Blocked, and Manual review classifications and Stage 2 prerequisite counts. The PowerShell operator entry point now consumes the exact Builder-approved release fingerprint, makes and verifies all three source backups, applies migrations on disposable restored copies first, compares live results with the rehearsed schema fingerprints, and automatically attempts three-plane restoration after a live failure. Inventory still requires reviewed migration authoring before registration. The six golden database procedure catalogs were also reverified at exact 1,236-procedure parity after the asset procedure module settings were normalized. [Read the staged upgrade guide](../builder-guide/staged-database-upgrades.html).

## 2026.09.15 - React styling support guide

Documentation Added [Support for React](../builder-guide/support-for-react.html), covering Tailwind, ordinary CSS, CSS Modules, inline styles, component libraries, and CSS-in-JS. The guide includes small source examples, publishing checks, and the distinction between hosted registered components and a developer-owned React build. It does not introduce new package installation or arbitrary-code execution capabilities.

## 2026.09.15 - Golden Discussion post-delete error contract synchronized

Fixed The golden core database's secured Discussion post-delete procedure now matches the reviewed error mapping for invalid requests, absent records, and denied removal. Execute-only application-role grants were preserved. The change was rehearsed with rollback, applied after a verified backup, and checked against the current export. Existing customer database copies are not silently upgraded by a golden database change.

## 2026.09.15 - Production-build customer browser verification

Verified A rebuilt frontend served by local IIS passed signed-in desktop and mobile checks on the seven pages installed in the million-record test tenant. Contacts passed paging, configurable page sizes, search, validation, create, saved edit, favorite/unfavorite, and removal through visible controls. Session reload and sign-out also passed. This is scoped local verification, not a public-production or every-module launch certification. Mobile contact-row star clipping remains a visual follow-up; external compute availability remains independently gated.

## 2026.09.15 - Contacts full pagination and page-size controls

Fixed Contacts now traverses the complete authorized directory instead of stopping at 2,000 rows. The secured procedure reads one bounded page plus a look-ahead row, returns `hasMore` for Next-button behavior, and marks totals exact on the last populated page. The standard directory supports 25, 50, 100, or 200 rows per page and a configurable initial `pageSize`. A fresh million-record tenant passed first, middle, final, and beyond-final paging through the compiled IIS runtime; the final authorized Contacts page returned 197 rows and `hasMore: false`. The reviewed procedure was installed in the golden Core database after a verified backup so future tenants inherit it.

## 2026.09.15 - Local IIS compiled-runtime verification

Improved The production-built React tenant frontend can now be staged on loopback-only IIS port 8080 using URL Rewrite and Application Request Routing. Localhost redirects to the selected tenant's routed localhost hostname; secured API calls stay same-origin and forward to local backend services. Login and Contacts, Calendar, and explainable-scoring passed desktop/mobile browser smoke checks. Missing API and asset paths return 404 instead of the React page. This verifies local IIS delivery, not a public production cutover: production secrets, persistent backend hosting, HTTPS, and external infrastructure still require their own deployment checks. Public site bindings were not changed.

## 2026.09.15 - Developer runtime gateway startup repair

Fixed The Developer API now registers the page executor required by its runtime bootstrap service through the existing secured Developer API database adapter. A dependency-resolution regression test covers the shared page/data adapter and identity forwarding. Golden-export test sentinels were updated to the reviewed current schema. Gateway throttling tests now exercise the authenticated partition and Retry-After instead of expecting anonymous calls to consume that budget. No database schema migration is required for these fixes.

## 2026.09.15 - Local battle-test rate-limit override

Improved Local test startup now supports an explicit high rate limit for bounded runtime and API testing. Production defaults and authorization checks remain unchanged. High-limit runs do not verify normal throttling behavior; rate-limit and Retry-After checks remain a separate test. Local startup can also skip shared billing-catalog setup.

## 2026.09.15 - Battle-test integrity classification and isolated report tests

Fixed Integrity checks distinguish verified zero-duration DataRole history boundary pairs from actionable constraint failures, retaining raw diagnostics and failing closed on unrecognized cases. Report unit tests use their own synthetic benchmark fixture instead of depending on a local historical run. Missing real performance evidence still fails release readiness. The retained test database passed 19 integrity invariants without deleting any data; this is not a production load certification.

## 2026.09.14 - Marketing pitch form restored to Classic ASP

Fixed Build My Pitch now posts to its same-origin ASP service with a session-bound human check and separate enabled/possible capability lists. The service reads its private OpenAI credential, targets Luna through Responses, and returns a downloadable Word-readable document without a public generated-file URL. Browser tests cover submission and download recovery. Live generation requires Responses write permission on the configured key; email delivery also requires working SMTP configuration.

## 2026.09.14 - Marketing site IIS availability restored

Fixed Removed a redundant local ASP setting that conflicted with the server's locked IIS configuration and prevented the marketing application from starting. The existing HTML-to-ASP mappings remain in place. Public page loads and the ASP health check now return successful responses; pitch-generation configuration is a separate integration check.

## 2026.09.14 - Homepage clarity and mobile navigation

Improved Public product pages now provide a mobile menu without requiring JavaScript. Homepage links lead to page design, customer signup, and the current developer kit. Database guidance distinguishes each SaaS from its customer organizations, service compute is identified as a deployment dependency, and MCP examples distinguish architectural concepts from published tool names.

## 2026.09.14 - Support navigation and documentation clarity

Improved Added a current developer-kit and version guide, role-based starting points, stable section links, and clearer public-kit versus account-kit instructions. Corrected SaaS database versus organization isolation wording, white-label reuse guidance, and public HTTPS versus origin configuration. The custom-service guide now identifies the pending compute dependency. Current kit checks read the release manifest; historical release notes retain their original versions.

## 2026.09.14 - Webhook example reliability fixes

Fixed Developer Kit 1.20.3 rejects corrupt or conflicting duplicate files, publishes complete event payloads atomically, serializes workers, isolates failed events after bounded retries, and enforces polling deadlines during requests and waits. Regression tests cover each failure. The Webhook Lab uses a versioned static release; Cloudflare handles public HTTPS, with an HTTP origin connection documented separately from the production origin-TLS target.

## 2026.09.14 - Webhook Lab and background-job examples

New `webhooks.buildwithhq.com` now has a deployable public reference site with dependency-free Node.js examples for exact-body HMAC verification, five-minute replay rejection, durable event-ID deduplication, fast acknowledgement, and bounded AI rebuild polling with required 429 `Retry-After` handling. The site does not collect customer deliveries; developers run the receiver in their own trusted backend. Developer Kit 1.20.2 includes the same sources and offline tests.

## 2026.09.14 - Developer webhook contract maintenance

Fixed Generated TypeScript now carries the documented `account | app` webhook subscription scope. Webhook update, secret rotation, delivery query, and dead-letter retry operations publish their real validation and not-found responses, while every Developer API 429 response declares the runtime `Retry-After` seconds header. The lifecycle example now uses the UUID event identifier emitted by the actual contract.

## 2026.09.14 - API pagination, filtering, limits, and versioning guide

New Developers now have one contract-backed operating guide for numbered module pages, organization cursor traversal, server-side filters, required 429 `Retry-After` handling, bounded transient retries, and OpenAPI fingerprint pinning. Developer Kit 1.20.1 includes a dependency-free JavaScript request helper and offline tests for rate-limit waits and both pagination families.

## 2026.09.14 - Developer Kit example portability

Fixed The Developer Kit assembler now rewrites the example catalog's OpenAPI reference to the portable kit path and removes repository-only.NET adapter and method names from the distributed copy. Public operation IDs, SDK methods, MCP tool names, scopes, requests, and the verified OpenAPI fingerprint remain available. The kit README now points developers to the portable catalog and copyable webhook signature verifier under `examples/`.

## 2026.09.14 - App-wide organization and user lifecycle webhooks

New Webhook subscriptions now distinguish backward-compatible `account` scope from `app` scope. A trusted SaaS backend can subscribe once for all customer organizations and receive nine sensitive, versioned events: organization create/update/deactivate, user create/update/deactivate, membership create/role change, and invitation acceptance. Lifecycle mutations stage events transactionally, role changes within one transaction collapse to final state, and the existing HMAC-signed retry/dead-letter worker performs delivery. Subscription ownership remains bound to the calling credential's AppAccount even when an app-scoped event names another customer organization; receivers gain visibility, not database or API authority.

## 2026.09.14 - Developer Kit 1.19.0 organization lifecycle

New Trusted SaaS backends can now list and search customer organizations, load their typed administration snapshot, update name/billing email, suspend or reactivate accounts, maintain DataRoles and Locations, create/resend/revoke hosted invitations, and transfer ownership through app-scoped Developer API routes. Mutations reuse reviewed CustomerCopy procedures, enforce revision fences and app/database binding, and write audit evidence. OpenAPI declares safe 404 and fenced 409 responses; all annotated email fields now publish `format: email`. Invitation tokens are hash-only in storage and returned once to the trusted backend for delivery; password acceptance remains on the hosted tenant authentication route.

## 2026.09.14 - Developer Kit 1.18.2 signup contract alignment

Fixed Customer-organization signup now declares its real retry semantics in OpenAPI: first creation and a matching idempotent replay both return HTTP `201`, with `created` distinguishing the outcome, while an owner-subject conflict returns HTTP `409` using the shared error envelope. Signup and tenant-user email inputs publish `format: email`, account status is constrained to `Active` or `Inactive`, and the connector rejects non-live credentials and duplicate normalized DataRole or Location keys before making a request.

## 2026.09.14 - Full support capability review

Improved All 173 support articles plus the home, section indexes, sitemap, and 404 surface were regenerated and checked in navigation order against the current capability contracts. Current documentation now consistently uses 273 Developer API operations across 211 paths, 199 promoted module operations, 23 cataloged first-class capabilities, and 43 MCP tools; historical release figures remain historical. Every article links to the generated API Map and first-class module inventory. Seller payout guidance now distinguishes BuildWithHQ ledger eligibility and transfer submission from Stripe Connect processing and bank-delivery timing, which Stripe controls.

## 2026.09.14 - SaaS CSS, design assets, and Developer API themes

New App Assets now provides app-scoped Custom CSS and design-file hosting. Trusted developer backends can also read and version-safely update the dashboard's app-wide theme, validated `--runtime-*` variables, and bounded design tokens through `GET/PUT /v1/apps/{saasAppId}/theme` and the connector SDK. Uploads now default to private, public delivery requires explicit selection, asset categories use a fixed enum, and authenticated binary-download errors remain JSON envelopes. Combined with page drafts/publishing and compiled CSS/assets, React, Tailwind, and pure React hosts have the complete supported styling workflow without exposing live credentials or running arbitrary customer build code in the API.

## 2026.09.14 - TailAdmin-style template design guide

New The Builder Guide now provides one end-to-end workflow for adapting a licensed professional React design into BuildWithHQ: establish token-safe CSS, refine shared primitives, customize module React at the correct ownership layer, edit every page through Puck, cover responsive and failure states, verify real lifecycle actions, then harvest and publish an immutable exact-version template. The guide keeps TailAdmin as visual reference while BuildWithHQ retains routing, identity, bindings, permissions and stored-procedure authority.

## 2026.09.14 - Developer Kit 1.18.1 customer signup bootstrap

New A SaaS builder's trusted marketing-site backend can now create a top-level customer organization, its first owner, protected owner authority, up to five initial DataRoles, and up to five initial Locations through one idempotent `createTenantAccount` call. The route reuses the reviewed Builder organization transaction, returns caller-key-to-ID maps, and writes the same routed AppAccount immediately shown in the Builder Organizations directory and the in-SaaS account administration area. The browser never receives the long-lived app credential: signup and login remain with the builder's verified identity provider/BFF, which exchanges the authenticated external subject for a short-lived delegated-user token. The golden CustomerCopy procedure was updated only after a verified COPY_ONLY/CHECKSUM backup and rollback-only creation/replay/limit proof, with zero fixture residue and no direct developer-role data, DDL, or Builder-procedure grant.

## 2026.09.13 - Local validation and release-contract maintenance

Fixed Local React, Puck, Developer Console, Developer Kit, OpenAPI, database-contract, and secured-service tests now follow the current generated contracts. Developer Console requests restore their short-lived access token through the secure refresh session before a protected call, text-file fingerprints are stable across LF/CRLF checkouts, the Qwen profile uses its approved 4096 native dimension, and SQL principal materialization includes the database-upgrade worker. Current package-lock audits for the Builder and tenant apps, Universal Inbox, page runtime, E2E harness, React kit, and local Puck report zero known vulnerabilities. The refreshed 1.18.0 Developer Kit remains local-only for `@buildwithhq/page-runtime`, and its assembler removes repository-only Local Puck aliases and internal monorepo paths from the customer ZIP while retaining them for direct source-tree tests. Physical GPU, Firecracker, live database, and production performance evidence remain environment-gated and are not claimed by this maintenance pass.

## 2026.09.12 - Developer Kit 1.18.0 local page runtime package

Fixed React and the local Puck editor now share one compiled, local-only `@buildwithhq/page-runtime` package from the kit's `packages/` directory. Locked `file:` dependencies replace the Vite/TypeScript aliases and the duplicated 577-line presentation parser. The hosted tenant app also resolves the compiled package through preserved local-package symlinks; its old source alias and direct TypeScript source inclusion are gone. The package allowlists compiled JavaScript and declarations only, emits no source maps, remains protected by `"private": true`, and passes packed-artifact checks in clean React 18 and React 19 projects. The route explorer now also accepts the delegated-user-only authentication mode used by the runtime page and binding operations. The optional `react/native/` source drop still requires the host's larger `@buildwithhq/universal-inbox` product dependency; that is its only unresolved native module and is not folded into this parser package. Normal `npm ci` still downloads declared third-party dependencies; no BuildWithHQ source is published to npm.

## 2026.09.12 - Developer Kit 1.17.4 uniform public conflict envelopes

Fixed The Developer API gateway now converts errors returned by imported tenant controllers into the canonical public `ApiErrorResponse`. Contacts and Checklist item update conflicts therefore include required `contractVersion`, `code`, `error`, and `correlationId` fields like every other public error. `TenantRuntimeErrorResponse` and its six media-type references have been removed from public OpenAPI, while native tenant-runtime routes retain their internal envelope.

## 2026.09.12 - Developer Kit 1.17.3 shared API errors and database posture

Improved All 528 rate-limit and internal-error responses now reference the single shared `ApiErrorResponse` component, eliminating 522 anonymous duplicate schemas for generated clients. Marketplace service guidance now states the database boundary in one place: API callers receive no SQL credentials; verified SaaS, tenant, and user identity is server-injected; and `bwhq_developer_api` has allow-listed procedure execution only, with no table rights or DDL authority.

## 2026.09.12 - Developer Kit 1.17.2 installed-service upgrade discovery

Fixed Installed-service discovery now excludes inactive installations and endpoints from duplicate-key detection, so an inactive prior package version cannot hide its active replacement from `GET /services` or the per-app OpenAPI projection. The secured procedure uses the repository DROP/CREATE convention, computes appliance executability and endpoint availability once, and uses collision-free errors `58708`/`58709`. A rollback-only golden-database proof installs v1, deactivates it, installs v2, and verifies that discovery exposes only available/invocable v2. The updated golden procedure was applied after a fresh COPY_ONLY/CHECKSUM backup passed RESTORE VERIFYONLY.

## 2026.09.12 - Developer Kit 1.17.1 marketplace contract evidence

Improved The per-app OpenAPI route now formally declares its SHA-256, ETag, and private no-store response headers, while installed service health and license states publish fixed enums for generated clients. Marketplace service guidance is linked from the system guide, API Map, headless workflow, and SDK guide. The ZIP also carries hash-bound review evidence for the exact secured discovery procedure, making its tenant-principal gate, requested-app installation filter, inactive-row exclusion, and exact endpoint-permission `canInvoke` decision independently inspectable without distributing server or backup topology.

## 2026.09.12 - Developer Kit 1.17.0 marketplace service contracts

New Trusted app backends can now list exact-version installed marketplace endpoint schemas through `GET /services` and download a per-app OpenAPI projection through `GET /openapi.json`. The projection combines the current static Developer API contract with available installed endpoints and publishes a deterministic contract fingerprint. MCP adds `buildwithhq.services.list` for dynamic schema discovery while retaining the generic invoke fallback. The new `appliances.read` scope grants metadata visibility only; execution still requires `appliances.invoke`, endpoint permission, exact artifact/license/health validation, secured source records, and MCP approval. The golden CustomerCopy received the reviewed secured discovery procedure after a verified COPY_ONLY/CHECKSUM backup.

## 2026.09.12 - Developer Kit 1.16.3 request contract normalization

Improved The OpenAPI document transformer now removes nullability from every required component property, gives required strings a minimum length of one, and publishes the finite request values enforced by current services and stored procedures. Literal enums now cover tenant identity, checklist item/evidence, conversation, Active Workplace, Work Order, reservation, Universal Inbox, AI search, inbound conversation, and payment policy requests. Optional enum fields reject explicit null consistently with the generated TypeScript client. Generic record and dynamic-module statuses remain intentionally extensible. The public contract remains 265 operations across 205 paths.

## 2026.09.12 - Developer Kit 1.16.2 tenant identity enums

Improved OpenAPI now publishes the exact `all | selected` location-scope values for tenant-user create and update requests and the exact `Active | Inactive` update status values enforced by the current tenant procedure. Create location scope is required and non-null; PATCH fields remain optional and nullable. Generated clients no longer accept arbitrary strings, and the tenant provisioning guide is linked from both kit indexes and both headless workflow entry points. The public contract remains 265 operations across 205 paths.

## 2026.09.12 - Builder-managed customer organizations

New SaaS builders can now create, view, edit, deactivate, and reactivate every customer organization inside an app they own, then add or update its tenant users, DataRoles, and Locations from the professional Organizations workspace. Initial organization, owner, owner authority, optional DataRoles, and optional Locations commit atomically. Subsequent changes use stale-write fences and safe deactivation where retained history or assignments prevent deletion. Every operation routes through the selected builder-owned SaaS database under reviewed stored procedures; record IDs never act as authority and the browser receives no database topology.

## 2026.09.12 - Developer Kit 1.16.1 tenant provisioning map

New A new kit-root tenant-provisioning and authentication guide maps signed-in Builder organization administration separately from public `bwk_live_` tenant-account and tenant-user provisioning and short-lived `bwu_live_` user delegation. It documents atomic owner, DataRole, and Location setup, revision-fenced Builder edits, public SDK methods and least-privilege scopes without weakening the credential boundary. The public contract intentionally remains 265 operations across 205 paths.

## 2026.09.12 - Developer Kit 1.16.0 runtime page embedding

New External applications can now load either a portable published page body or the complete SaaS shell through a delegated-user-only runtime client, then resolve registered block bindings in a secured batch. The three new routes reuse native entitlement fallback, component contracts, DataRole and Location scope, record authorization, tenant routing, stored procedures, and page audit. Body reads omit design tokens by default so the host theme wins. The binding request publishes its required, unique 1..24-key collection bounds for every generated client, and all runtime error statuses reuse the shared API error contract. The generated contract now contains 265 operations across 205 paths, and all 37 double schemas are numeric rather than numeric-string unions.

## 2026.09.12 - Developer Kit 1.15.3 body schema normalization

Improved Integer normalization now runs through the global OpenAPI schema transformer instead of only at the operation-parameter layer. All 1,957 integer schema nodes across parameters, request bodies, response bodies, and reusable components exclude numeric strings and leaked regex patterns; the 137 genuinely nullable integer nodes retain `null | integer` rather than being incorrectly narrowed. Generated clients now receive numeric `contractVersion`, paging, count, sort order, priority, and integer custom-field contracts throughout the API.

## 2026.09.12 - Developer Kit 1.15.2 integer contract normalization

Improved The OpenAPI generator now normalizes all 77 integer parameters at the contract boundary instead of special-casing two Record Graph fields; none retain the ASP.NET integer/string union or numeric regex artifact. Record Graph additionally publishes its actual service rejection bounds for record search, related knowledge, and contextual candidates. The package gate directly compares both distributed `presentation.ts` copies with the LF-normalized canonical page-runtime source and with each other, so newline normalization cannot hide implementation drift. Current kit and API43 copy also use the generated 262-operation and 199-module-operation totals.

## 2026.09.12 - Developer Kit 1.15.1 contract alignment

Improved Record Graph OpenAPI now publishes integer-only `maxDepth` 1-5 and `maxNodes` 2-200 constraints and requires non-empty `toRecordId` and `relationKey` association fields. The API Map distinguishes vendor-only regeneration inputs from the two hash-verifiable shipped contracts and states that Record Graph is REST/SDK-only in the intentionally curated 42-tool MCP release. Native React extension dependencies and self-contained Puck-vendored sources are labeled explicitly, the stale 243-operation sentence is corrected to 262, and every UTF-8 ZIP entry uses LF line endings. The release builder now refreshes the operation and recipe inputs before generating the hash-bound API Map, preventing a successful write from immediately making its own map stale.

## 2026.09.12 - Developer Kit 1.15.0

New The shared BuildWithHQ/API43 Developer and Headless API ZIP now includes `docs/API-MAP.md`: all 23 first-class capability surfaces, all 18 Build This product routes, complete add/view/edit/remove/favorite/relationship/file/activity matrices, module-specific actions, and the secured bounded recursive Record Graph workflow. The deterministic archive carries all 262 published operations across 202 paths, regenerates and verifies the API Map before packaging, and retains exact authentication, SDK coverage, OpenAPI, recipe, React, MCP, and headless-server contracts.

## 2026.09.12 - Complete API route and usability inventory

Improved The new API Map provides a reproducible, source-backed route and day-to-day usability inventory for all 23 first-class capabilities and all 18 Build This products. It distinguishes the 194 authenticated tenant-runtime routes used by rendered SaaS pages from the 193 published Developer API module routes, classifies list/view, add, edit/modify, remove, favorite, association, files/evidence, activity, and module-specific actions, and maps every canonical Build This recipe step plus every additional operation explicitly named by the runnable solution manifests. A dedicated guide shows how any eligible canonical record can use registered relationship types to build a bounded recursive graph, safely supporting multi-level and cyclic associations without inheriting authorization through an edge. Product-managed record families have explicit lifecycle matrices, while derived views point back to their native secured owner instead of duplicating destructive actions.

## 2026.09.12 - Support Tickets production solution

New Support Tickets is now an operable mailbox-to-resolution SaaS over native Conversations and Universal Inbox. One managed Support Playbooks family uses 14 database-backed dynamic/custom fields across five responsive workspaces, while Conversations retain thread history and Inbox owns ticket identity, attention, assignment, priority, service level, resolution state, and `ActivityVersion`. Current secured contracts provide mailbox-owner configuration, atomic stable ticket allocation, customer replies on the canonical thread, explicit resolution, automatic reopen on later inbound mail, and HTTP conflict for stale replies. The routed journey also proved complete playbook lifecycle, gray/gold 25-pixel favorites, relationships, files, activity, cleanup, and owner/permission boundaries; golden/disposable SQL policy and desktop/mobile Chromium rendering passed. Template Library packaging remains separate.

## 2026.09.12 - Checkoff & Approval production solution

New Checkoff & Approval is now an operable evidence-backed checklist and human-signoff SaaS. One managed Verification Programs family uses 12 database-backed dynamic/custom fields across five responsive workspaces, while native Checklists & Signoffs, Files, Workflow, Universal Inbox, Favorites, relationships, and activity retain ownership. The current secured contracts provide template list/read/create/revision-fenced update/deactivation, exact run snapshots, up to 1,000 bounded items, verified document/photo proof, idempotent submit, stale-context protection, reject/revise/resubmit, and approval. The public Developer API recipe now exposes the complete template lifecycle. The routed journey proved proof replacement after rejection, gray/gold 25-pixel favorites, relations, files, activity, and cleanup; golden/disposable SQL policy, developer execute grants, OpenAPI/SDK checks, and desktop/mobile Chromium rendering passed. Template Library packaging remains separate.

## 2026.09.12 - Reservations production solution

New Reservations is now an operable capacity-protected booking SaaS over the current first-class module. Reservation Policies use 10 database-backed dynamic/custom fields; native products, Reservations, Contacts, Calendar, Files, Favorites, relationships, activity, tenant payment controls, and durable follow-ups retain their secured typed APIs and reviewed stored procedures. Five responsive workspaces cover booking, operations, product/capacity setup, customers, and payment/follow-up. The routed journey proved product lifecycle, authenticated booking, idempotent replay, server-locked capacity, party limits, active-user assignment, free-booking payment state, paid-booking payment-method enforcement, stale-write denials, follow-ups, gray/gold 25-pixel favorites, relations, files, check-in/completion, audited cancellation, and cleanup. Golden/disposable procedure policy and desktop/mobile Chromium rendering passed. Anonymous checkout and Template Library packaging remain intentionally separate.

## 2026.09.12 - FieldService production solution

New FieldService is now an operable request-to-approved-closeout SaaS refreshed from the repository's existing reference implementation. Template-owned Change Requests use 12 database-backed dynamic/custom fields; native Contacts own customers and team profiles, Work Orders own jobs and legal transitions, Calendar owns scheduling, Files and Checklists & Signoffs own evidence and approval, and Conversations plus Universal Inbox own communication and attention. Six responsive workspaces cover dispatcher, customer, technician, schedule, evidence, manager approval, and follow-up work. The routed journey proved lifecycle, gray/gold 25-pixel favorites, relations, assignment, schedule, file attachment, checklist photo proof, approval, follow-up, stale-write denials, and cleanup. Golden/disposable procedure parity, the deterministic reference bundle, and desktop/mobile Chromium rendering passed. Tenant billing remains explicitly deferred; Template Library packaging remains separate.

## 2026.09.12 - ActiveWorkplace production solution

New ActiveWorkplace is now an operable recursive-record coordination SaaS. Two managed record families use 16 database-backed dynamic/custom fields for pinnable work items and reusable graph playbooks across four responsive workspaces. The native first-class module owns idempotent pinning, bounded cyclic graphs, participants, responsibilities, deterministic Pulse, retained activity and snapshots, and read-only playback; Universal Inbox remains the shared attention layer. Current secured typed APIs and reviewed stored procedures provide complete record lifecycle, gray/gold 25-pixel favorites, registered relationships, stale-write protection, and current tenant, DataRole, location, and AI-read authorization. The routed journey proved pin, update, favorite, relation, participant, activity, graph-refresh, playback, resolve, and cleanup behavior. Golden/disposable procedure parity and desktop/mobile Chromium rendering passed. Template Library packaging remains intentionally separate.

## 2026.09.12 - AssetOps production solution

New AssetOps is now an operable asset, inspection, and maintenance SaaS. Five managed record families use 47 database-backed dynamic/custom fields for sites, assets, inspection findings, parts usage, and service history across five responsive workspaces. Native Contacts, Work Orders, Checklists & Signoffs, Files, Calendar, Favorites, record relationships, and activity preserve their current secured typed APIs and reviewed stored procedures. The routed journey proved customer and asset lifecycle, 25-pixel gray/gold favorites, recursive relationships, signature-verified photo proof, inspection approval, technician assignment, legal Requested-to-Completed work-order transitions, and cleanup. Location, assignee, invalid-transition, and stale-write denials passed, as did golden/disposable procedure parity and desktop/mobile Chromium rendering. Template Library packaging remains intentionally separate.

## 2026.09.12 - CaseFlow production solution

New CaseFlow is now an operable controlled case-management SaaS. Seven managed record families use 53 database-backed dynamic/custom fields for cases, parties, immutable stage evidence, tasks, evidence, decisions, and approvals across five responsive workspaces. Current secured typed APIs and reviewed stored procedures provide complete lifecycle, gray/gold 25-pixel favorites, registered relationships, secured files, activity, and personal Favorites. A server-owned transition procedure fixes new cases at Intake, serializes adjacent stages, rejects direct, stale, invalid, and out-of-order changes, and requires an approved Checklists & Signoffs run before Decision or Closed. The checklist revision and Universal Inbox `ActivityVersion` fences survive submission and approval. Five role policies, two locations, golden/disposable procedure parity, the routed intake-to-decision journey, and desktop/mobile Chromium rendering passed. Template Library packaging remains intentionally separate.

## 2026.09.12 - Headless SaaS DB production solution

New Headless SaaS DB is now an operable API-first managed backend with five record families, 35 database-backed dynamic/custom fields, and five professional responsive workspaces. Its exported server-side TypeScript client covers schema/search, complete record lifecycle, gray/gold 25-pixel favorites, registered relationship add/remove, inbound endpoints, webhooks, delivery retries, and correlation logs. A working React administration client keeps live app credentials and physical database routing inside a same-origin BFF. The routed public API journey proved create, read, update, cleanup/remove, favorite/unfavorite, relationship add/remove, read-only denial, webhook creation and signing-secret rotation, safe correlations, and secret/SQL authority exclusion. Golden and disposable stored-procedure policy, SDK routes, generated API recipes, and desktop/mobile Chromium rendering passed. Template Library packaging remains intentionally separate.

## 2026.09.12 - OpsAtlas production solution

New OpsAtlas is now an operable owned and revisioned operating-memory SaaS. Five managed record families use 35 database-backed dynamic/custom fields for operating domains, approved source registers, review programs, gap triage, and governed workflow links across five responsive workspaces. The native Knowledge Core supplies draft, view, edit, immutable revision, publish, archive/restore, collection, ownership, review, question, feedback, favorite, relation, file, and activity workflows through current secured typed APIs and reviewed procedures. Published AI-eligible sources enter the canonical multimodal pipeline; role-aware cited answers apply tenant, DataRole, location, field, record, and `CanAiReadRecords` policy before context, preserve visual evidence, and create a Knowledge Question instead of fabricating unsupported guidance. The routed author-to-publish/favorite/relation/ingest/answer journey, database policy, and desktop/mobile Chromium proof passed. Template Library packaging remains intentionally separate.

## 2026.09.12 - CompanyIQ production solution

New CompanyIQ is now an operable permission-aware company-knowledge and opportunity-intelligence SaaS. Five managed record families use 40 database-backed dynamic/custom fields for knowledge sources, business context, evidence-backed insights, cited evidence, and governed suggested actions across five responsive workspaces. Current secured typed APIs and reviewed stored procedures provide complete lifecycle, gray/gold 25-pixel favorites, registered relationships, files, activity, bounded ingestion, and cited semantic search. Retrieval filters the represented user's tenant, DataRole, location, record, field, and `CanAiReadRecords` scope before model context and preserves text and visual evidence through the canonical 256, 1024, and 1998-dimensional multimodal lanes using the current Qwen3-VL 8B profile. Golden/disposable database policy, the routed lifecycle/favorite/relation/AI product journey, and desktop/mobile Chromium proof passed. Template Library packaging remains intentionally separate.

## 2026.09.12 - CustomerPortal production solution

New CustomerPortal is now an operable branded external-collaboration SaaS with six managed record families and 54 database-backed dynamic/custom fields for requests, milestones, approvals, shared updates, private internal operations, and visibility reviews across five responsive workspaces. Explicit customer and internal-staff User Types have separate reviewed menus and assignment policies; DataRoles and shared/internal Locations enforce the disclosure boundary. Current secured typed APIs and stored procedures provide create, view, edit, safe remove, gray/gold 25-pixel favorites, registered record relationships, files, messages, activity, and personal Favorites. External users can work customer-safe records while internal pages, records, fields, search hits, graph nodes, and cross-boundary edges remain concealed. The routed internal/external API and SQL isolation journey plus desktop/mobile Chromium proof passed. Template Library packaging remains intentionally separate.

## 2026.09.12 - RelateEverything production solution

New RelateEverything is now an operable relationship-first CRM over canonical Records and RecordRelations. Native Contacts retain complete create, view, edit, 25-pixel favorite, and safe removal lifecycle; six managed dynamic/custom-field record families cover companies, workstreams, opportunities, relationship context, duplicate review, and connected automations across five responsive workspaces. Current secured typed APIs and stored procedures provide lifecycle, favorite/unfavorite, registered relation add/remove, evidence files, activity, AI Insights, and personal Favorites. The relationship graph applies current tenant/SaaS identity, active DataRole, location, and direct-conversation participation rules before adding nodes, then returns edges only when both endpoints are authorized. Connected automations remain approval-required for material mutations. Golden/disposable procedure and graph policy checks, the routed native-Contact and six-entity journey, and desktop/mobile Chromium proof all passed. Template Library packaging remains intentionally separate.

## 2026.09.12 - TeamBox production solution

New TeamBox is now an operable shared communications command center. Native Conversations retain thread, message, reply, favorite, and removal lifecycle; Universal Inbox remains a bounded attention and ownership projection with the `ActivityVersion` stale-context fence. Six managed dynamic/custom-field record families cover channel intake policies, queues, routing rules, classification review, SLA policies, and handoff playbooks across five responsive workspaces. Current secured typed APIs and stored procedures provide complete lifecycle, favorite/unfavorite, record relations, evidence files, activity, and personal Favorites. Classification reviews retain the native Conversation pointer, authorized evidence, confidence, model/harness version, and reviewed disposition, while customer-facing replies and material actions stay policy- or human-approval gated. The initial Inbox view is bounded to 25 records so every visible source can resolve its accurate favorite state without exhausting the tenant request budget. Golden/disposable procedure verification, the routed native-conversation and six-entity journey, stale-write rejection, and desktop/mobile Chromium proof all passed. Template Library packaging remains intentionally separate.

## 2026.09.12 - Northstar production solution

New Northstar is now an operable evidence-backed executive-intelligence SaaS with six managed record families for versioned metric definitions, source-watermarked observations, forecasts, material signals, scenarios, and frozen briefings. Five professional responsive workspaces provide the executive scorecard, material-change queue, metric/forecast drill-down, scenario comparison, and executive briefing/decision log. Current secured typed APIs and stored procedures provide complete lifecycle, favorite/unfavorite, record relations, evidence files, activity, and personal Favorites. Secured AI Insights remain read-only synthesis; briefings retain exact evidence and assumptions, model/harness lineage, reviewer and disposition, and a frozen timestamp, while financial commitments and operating writes remain approval-gated. Golden/disposable parity, fail-closed AI roles, the routed six-entity journey, and desktop/mobile Chromium proof all passed. Template Library packaging remains intentionally separate.

## 2026.09.12 - LaunchPilot production solution

New LaunchPilot is now an operable governed marketing-operations SaaS with six managed record families for campaigns, consent-aware audience snapshots, approved asset versions, channel runs, experiments, and performance snapshots. Five professional responsive workspaces provide campaign command and calendar, campaign detail, audience/consent review, asset and launch approval, and experiment/performance analysis. Current secured typed APIs and stored procedures provide complete lifecycle, favorite/unfavorite, record relations, evidence files, activity, and the personal Favorites workspace. Universal Inbox and the reviewed Workflow approval contract retain launch decisions; channel records freeze audience, asset, spend, idempotency, and evidence while remaining non-activatable until configured approval. Golden/disposable procedure parity, fail-closed AI roles, the routed six-entity journey, and desktop/mobile Chromium create-favorite-remove proof all passed. Template Library packaging remains intentionally separate.

## 2026.09.12 - Resolve production solution

New Resolve is now an operable permission-aware support SaaS. Native Conversations retain customer communication, Universal Inbox remains the attention layer, and Knowledge Core supplies versioned Official policy evidence. Four managed record families cover customer context, issues, cited resolution suggestions, and escalations across five professional responsive pages. Current secured typed APIs and stored procedures provide lifecycle, favorite/unfavorite, record relations, evidence files, activity, and the personal Favorites workspace. Customer-facing and material operations remain policy- or human-approval gated with the Inbox `ActivityVersion` stale-context fence. Golden/disposable procedure parity, fail-closed AI roles, the routed API journey, and desktop/mobile Chromium create-favorite-remove proof all passed. Template Library packaging remains intentionally separate.

## 2026.09.12 - SignalIQ production solution

New SignalIQ is now an operable revenue-intelligence SaaS solution with six managed record families for accounts, contacts, opportunities, signals, versioned score snapshots, and recommendations. Five professional responsive pages provide a revenue command center, Account 360, buying-signal feed, governed next-best-action queue, and explainable scoring. Every managed entity uses current secured typed APIs and stored procedures for create, view, edit, remove, favorite/unfavorite, relationships, files, and activity. Secured AI Insights are read-only findings; recommendations retain evidence, confidence, score/model versions, ownership and expiry, while material actions remain behind policy or human approval. Golden/disposable procedure parity, fail-closed AI roles, the routed six-entity API journey, and desktop/mobile Chromium create-favorite-remove proof all passed. Template Library packaging remains intentionally separate.

## 2026.09.12 - CrewOS production solution

New CrewOS is the first product-specific Build This concept completed as an operable SaaS solution. It includes a professional governed AI team command center, owner-scoped add/edit/security/deactivate controls over the current GoClaw team contracts, three managed record families, six published pages, shared gray/gold 25-pixel favorites, secured file attachments, record relationships and activity, Universal Inbox approvals, and the existing ActivityVersion stale-context fence. Its materializer now adds installed pages to the verified installer User Type menu through the reviewed menu procedure. The complete API journey and desktop/mobile Chromium experience passed against a route-resolved disposable tenant. CrewOS remains a production solution rather than a Template Library listing until the later exact-version packaging task.

## 2026.09.12 - Build This production-solution program

New The eighteen Build This concepts now have a dedicated production build queue, separate from the Template Library. A shared Professional Foundation has been materialized into a guarded, route-resolved disposable tenant and exercised through its real React UI and APIs for create, view, update, remove, favorite/unfavorite, record relationships, and activity. Desktop and mobile rendering use the current TailAdmin-derived visual system. Each product will be built and proven as an operable SaaS solution before an exact-version reusable template is published; the remaining product solutions are not yet represented as complete.

## 2026.09.12 - Universal Favorites and database-contract hardening

Improved Record surfaces can now load the signed-in user's secured favorite state and show the shared 25-by-25-pixel star: gray when unsaved and gold when favorited. The Favorites workspace remains the personal cross-module destination. The missing state procedure was restored to the CustomerCopy golden database, all six golden exports now rebuild cleanly with exact live/export parity across 1,210 stored procedures, and the active npm dependency scopes were upgraded to resolve the reviewed Vitest, Tiptap, and fast-uri advisories.

## 2026.09.09 - Tenant presentation administration and live developer kits

New Builders can explicitly allow shared User Types and menu/page subsets for tenant administration. Account owners can narrow and reorder those menus without gaining data authority, and download a deterministic developer ZIP containing only their active module routes, current pages, bindings, compatibility versions, working typed clients, React starters, and offline validation—with no credential, fixture, or placeholder contract.

## 2026.09.09 - Hosted tenant user invitations

New Tenant account owners can send expiring, single-use hosted invitations with snapshotted User Type, DataRole, and location assignments. Recipients establish their own password; external/headless users remain passwordless unless explicitly invited. Tokens are hash-only in storage, fragment-only in email links, POST-only during resolution, revocable, rotation-safe, and replay-protected.

## 2026.09.08 - Exact API authentication catalogs

New Developer Kit 1.14.2 derives `public`, `draft-app`, `live-app`, and `live-or-delegated` labels directly from each OpenAPI operation. Product recipes carry the same accepted clients, regenerate during release builds, and fail the gate if their operation hash or authentication contracts drift. The extension guide also documents the current opaque invocation identity boundary without claiming a token-introspection API.

## 2026.09.08 - Developer Kit contract clarity

New Developer Kit 1.14.1 publishes required arguments for all 42 MCP tools, full concurrency-fenced schemas and per-app approval metadata for sensitive writes, and separate OpenAPI schemes for draft-app, live-app, and delegated-user credentials. A twelve-chapter system guide explains the platform, all first-class modules, React and page JSON, exact-version forking, headless use, MCP, and private VM/PostgreSQL extension services.

## 2026.09.08 - Approval-gated MCP module writes

New Developer Kit 1.14.0 adds real checklist-item toggle and Work Order status-change tools. Both use the same secured service and stored procedure as their REST operation, require the exact module write scope and optimistic-concurrency token, and remain undiscoverable until a permitted builder approves the capability for that SaaS app.

## 2026.09.07 - Local Puck binding editor

New Developer Kit 1.13.0 includes a self-contained local Puck 0.23.0 editor over the production BuildWithHQ adapter. Developers can open canonical page JSON, set registered binding keys and bounded data paths, download the result, and save and validate a real unpublished draft through a trusted-server command without exposing credentials to Vite.

## 2026.09.07 - HTML-to-Puck developer converter

New Developer Kit 1.12.0 converts static HTML or a `dist/index.html` entry into deterministic, schema-valid Professional Foundation page JSON. It ships an annotated control-panel example, strict lossy-conversion reporting, catalog-enforced component properties, and intentionally excludes scripts, arbitrary CSS, credentials, identity and inferred bindings.

## 2026.09.06 - Headless end-user delegation

New App-bound Developer API clients can create tenant accounts and passwordless external users, assign DataRoles and Locations, issue 2-15 minute delegated-user tokens, revoke them, and deactivate users. Module calls execute as that exact user and retain the originating API client for audit.

## 2026.09.06 - Complete API43 / headless surface

New The generated v1 contract publishes 237 operations across 192 paths, including all 181 promoted first-class module operations, nine tenant identity operations, and the MCP Streamable HTTP transport.

## 2026.09.07 - Developer Kit 1.10.0

New Eighteen Build This concepts now ship as contract-generated API recipes with exact routes, least-privilege scopes, SDK methods, request schemas, response statuses, delegated-user boundaries, and isolation/idempotency release assertions. The kit retains the secured module MCP reads, browser credential guard, and tested DeepSeek Harness setup from 1.9.2.

## 2026.09.07 - Draft and live Developer API keys

New Draft-only `bwk_draft_` credentials can edit and validate unpublished page JSON without gaining tenant-data or publication authority. Publishing now requires an explicit `bwk_live_` credential, `pages.publish`, the exact draft-history ID, and the expected live version. Developer Kit 1.11.0 contains all 243 operations and the separate draft/live TypeScript clients.

## 2026.09.07 - Tenant account-owner administration

New Tenant account owners can manage users, DataRoles and locations, review last-login information, and generate a secret-free developer ZIP containing only their account identity and active module capabilities. The console and ZIP remain tenant-session authorized; account IDs never act as credentials.

## 2026.09.05 - Professional presentation system

New Metrics, entity and progress lists, charts, grids, timelines, tasks, row actions, icons, and responsive layouts can be combined into original admin experiences.

## 2026.09.05 - First-class module gallery

New Every cataloged first-class feature has validated sample and live pages, with save-to-Builder and page-JSON downloads.

## 2026.09.05 - Copyable React module guides

Improved First-class feature articles now include complete styled and unstyled React starting points, data contracts, loading, empty, error, and action behavior.

## 2026.09.05 - Responsive presentation hardening

Improved Wide grids, charts, badges, and trailing values remain contained and usable on desktop, tablet, and small mobile screens.

## 2026.09.04 - SaaS themes

New Version-fenced themes carry mode, CSS variables, and design tokens from the database to painted React pixels.

## 2026.09.04 - Interactive presentation actions

New Checklist toggles and declared grid actions preserve entitlement, revisions, conflict refresh, failure rollback, and in-flight state.

## 2026.09.04 - Embedded Universal Inbox

New Builders can place a full Inbox experience on a normal page and launch it from a menu while retaining the top-bar attention view.

## 2026.09.03 - Runtime-observed catalog

Improved Static inventory joins runtime observations so route-to-procedure pairs are evidence and the delta identifies untested operations.

## 2026.09.03 - Developer route explorer

New Developers can search the published API catalog by route, operation, module, verb, scope, and authentication requirement.

## 2026.09.03 - Database-backed theme contracts

New Procedure-only, version-fenced contracts read and write SaaS themes and surface them through tenant bootstrap without granting direct table access.

## 2026.09.02 - Tenant session lifecycle

Improved Sessions restore across browser reloads and expired sessions return users to a clear sign-in state.

## 2026.09.02 - Negative-path API hardening

Improved Missing and foreign identifiers remain indistinguishable while ordinary misses return 404 instead of outage-like 503 responses.

## 2026.09.02 - Security rejection audit

New Rejected tenant identities and other reviewed security events are recorded with correlation evidence so blocked attacks are observable.

## 2026.09.01 - Checklists & Signoffs

New Checklists attach to records, tickets, projects, and work orders, support up to 1,000 items, and accept documents or photos as proof.

## 2026.09.01 - Universal data presentation blocks

New Reviewed API results can render as metric sets, entity lists, progress lists, series charts, data grids, and timelines without loading an unbounded record graph into the page.

## 2026.08.30 - Multi-tenant battle testing

Improved Realistic tenant, API, permission, workflow, Inbox, AI, and routing journeys feed a repeatable readiness harness.

## 2026.08.29 - Universal Inbox ticketing

New Inbound email addresses can be ticketing channels with permanent keys, assignment, SLA, resolution, approval, and ActivityVersion protections.

View previous 10View next 10

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/changelog/index-notes.html).