@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/forms.md

@@ -0,0 +1,1542 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.forms`: Forms
+
+35 operations (15 read, 14 write, 2 destructive, 4 external).
+
+No hand-written client covers this area. Call it through `g8.api.forms.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [forms.d.ts](forms.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`addFormGroupMembers`](#op-addformgroupmembers) | `POST /api/v1/forms/groups/{group_id}/members` | write | `forms:write` | Add Form Group Members |
+| [`captureFormPreview`](#op-captureformpreview) | `POST /api/v1/forms/{form_key}/preview` | write | `forms:write` | Capture Form Preview |
+| [`createFormBackfill`](#op-createformbackfill) | `POST /api/v1/forms/{form_key}/backfills` | external | `forms:run` | Create Form Backfill |
+| [`createFormGroup`](#op-createformgroup) | `POST /api/v1/forms/groups` | write | `forms:write` | Create Form Group |
+| [`deleteFormGroup`](#op-deleteformgroup) | `DELETE /api/v1/forms/groups/{group_id}` | destructive | `forms:delete` | Delete Form Group |
+| [`getFormActivity`](#op-getformactivity) | `GET /api/v1/forms/{form_key}/activity` | read | `forms:read` | Get Form Activity |
+| [`getFormBackfill`](#op-getformbackfill) | `GET /api/v1/forms/{form_key}/backfills/{job_id}` | read | `forms:read` | Get Form Backfill |
+| [`getFormFields`](#op-getformfields) | `GET /api/v1/forms/{form_key}/fields` | read | `forms:read` | Get Form Fields |
+| [`getFormOverview`](#op-getformoverview) | `GET /api/v1/forms/{form_key}/overview` | read | `forms:read` | Get Form Overview |
+| [`getFormPlacements`](#op-getformplacements) | `GET /api/v1/forms/{form_key}/placements` | read | `forms:read` | Get Form Placements |
+| [`getFormPreview`](#op-getformpreview) | `GET /api/v1/forms/{form_key}/preview/{preview_id}` | read | `forms:read` | Get Form Preview |
+| [`getFormRouteRecommendations`](#op-getformrouterecommendations) | `GET /api/v1/forms/{form_key}/route/recommendations` | read | `forms:read` | Get Form Route Recommendations |
+| [`getFormSubmissionTrace`](#op-getformsubmissiontrace) | `GET /api/v1/forms/{form_key}/submissions/{submission_id}/trace` | read | `forms:read` | Get Form Submission Trace |
+| [`getSiteAudit`](#op-getsiteaudit) | `GET /api/v1/forms/site-audit` | read | `forms:read` | Get Site Audit |
+| [`listFormGroups`](#op-listformgroups) | `GET /api/v1/forms/groups` | read | `forms:read` | List Form Groups |
+| [`listForms`](#op-listforms) | `GET /api/v1/forms` | read | `forms:read` | List Forms |
+| [`listSavedFormViews`](#op-listsavedformviews) | `GET /api/v1/forms/views/saved` | read | `forms:read` | List Saved Form Views |
+| [`pauseFormDelivery`](#op-pauseformdelivery) | `POST /api/v1/forms/{form_key}/delivery/pause` | external | `forms:run` | Pause Form Delivery |
+| [`previewFormMapping`](#op-previewformmapping) | `POST /api/v1/forms/{form_key}/mapping/preview` | read | `forms:read` | Preview Form Mapping |
+| [`previewUnidentifiedGrouping`](#op-previewunidentifiedgrouping) | `GET /api/v1/forms/unidentified/grouping` | read | `forms:read` | Preview Unidentified Grouping |
+| [`removeFormGroupMembers`](#op-removeformgroupmembers) | `POST /api/v1/forms/groups/{group_id}/members/remove` | write | `forms:write` | Remove Form Group Members |
+| [`requestSiteAuditScan`](#op-requestsiteauditscan) | `POST /api/v1/forms/site-audit/scan` | write | `forms:write` | Request Site Audit Scan |
+| [`resumeFormDelivery`](#op-resumeformdelivery) | `POST /api/v1/forms/{form_key}/delivery/resume` | external | `forms:run` | Resume Form Delivery |
+| [`retryFormDelivery`](#op-retryformdelivery) | `POST /api/v1/forms/deliveries/{receipt_id}/retry` | external | `forms:run` | Retry Form Delivery |
+| [`rollbackFormRoute`](#op-rollbackformroute) | `DELETE /api/v1/forms/{form_key}/route` | destructive | `forms:delete` | Rollback Form Route |
+| [`saveFormMapping`](#op-saveformmapping) | `POST /api/v1/forms/{form_key}/mapping/save` | write | `forms:write` | Save Form Mapping |
+| [`saveFormRoute`](#op-saveformroute) | `PUT /api/v1/forms/{form_key}/route` | write | `forms:write` | Save Form Route |
+| [`saveFormView`](#op-saveformview) | `PUT /api/v1/forms/views/saved/{view_id}` | write | `forms:write` | Save Form View |
+| [`searchFormSubmissions`](#op-searchformsubmissions) | `POST /api/v1/forms/{form_key}/submissions` | read | `forms:read` | Search Form Submissions |
+| [`setUnidentifiedGrouping`](#op-setunidentifiedgrouping) | `PUT /api/v1/forms/unidentified/grouping` | write | `forms:write` | Set Unidentified Grouping |
+| [`syncUnidentifiedGroup`](#op-syncunidentifiedgroup) | `POST /api/v1/forms/unidentified/groups/sync` | write | `forms:write` | Sync Unidentified Group |
+| [`testFormRoute`](#op-testformroute) | `POST /api/v1/forms/{form_key}/route/test` | write | `forms:write` | Test Form Route |
+| [`updateFormGroup`](#op-updateformgroup) | `PATCH /api/v1/forms/groups/{group_id}` | write | `forms:write` | Update Form Group |
+| [`updateFormRegistry`](#op-updateformregistry) | `PATCH /api/v1/forms/{form_key}` | write | `forms:write` | Update Form Registry |
+| [`updateSiteAuditFinding`](#op-updatesiteauditfinding) | `PATCH /api/v1/forms/site-audit/findings/{finding_id}` | write | `forms:write` | Update Site Audit Finding |
+
+---
+
+<a id="op-addformgroupmembers"></a>
+
+### `g8.api.forms.addFormGroupMembers(input)`
+
+**Add Form Group Members**
+
+- HTTP: `POST /api/v1/forms/groups/{group_id}/members`
+- operationId: `add_form_group_members_forms_groups__group_id__members_post` (also callable as `g8.api.call("add_form_group_members_forms_groups__group_id__members_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `forms:write`
+
+Add inventory rows to a group. Existing members stay.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.group_id` | `string` | yes | The group's id. |
+| `body` | `FormGroupMembersRequest` | yes | Request body; fields below. |
+
+Body fields (`FormGroupMembersRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.members` | `Array<FormGroupMemberRef>` | yes | min items 1, max items 200 |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.addFormGroupMembers({
+  path: { group_id: "id" },
+  body: { members: [{ form_key: "example", source_id: "id" }] },
+});
+```
+
+---
+
+<a id="op-captureformpreview"></a>
+
+### `g8.api.forms.captureFormPreview(input)`
+
+**Capture Form Preview**
+
+- HTTP: `POST /api/v1/forms/{form_key}/preview`
+- operationId: `capture_form_preview_forms__form_key__preview_post` (also callable as `g8.api.call("capture_form_preview_forms__form_key__preview_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `forms:write`
+
+Queue a screenshot of this form on one page it was actually seen on.
+
+ASYNCHRONOUS: poll `GET /forms/{form_key}/preview/{preview_id}`. A page the
+form was never observed on is a 404 - it captures real placements only.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | The form's `form_key` (the `id` from `GET /forms`). |
+| `body` | `FormPlacementPreviewRequest` | yes | Request body; fields below. |
+
+Body fields (`FormPlacementPreviewRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.page_url` | `string` | yes | A page the form was actually seen on. min length 8, max length 4096 |
+| `body.source_id` | `string` | yes | The site (write key) the form is installed on. min length 1, max length 500 |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.captureFormPreview({
+  path: { form_key: "example" },
+  body: { page_url: "https://example.com", source_id: "id" },
+});
+```
+
+---
+
+<a id="op-createformbackfill"></a>
+
+### `g8.api.forms.createFormBackfill(input)`
+
+**Create Form Backfill**
+
+- HTTP: `POST /api/v1/forms/{form_key}/backfills`
+- operationId: `create_form_backfill_forms__form_key__backfills_post` (also callable as `g8.api.call("create_form_backfill_forms__form_key__backfills_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `forms:run`
+
+Deliver submissions captured in a window through the form's current route.
+
+`preview` DEFAULTS TO TRUE, and that default is the safety: a real backfill
+delivers real leads to a real destination and there is no undo. Preview,
+read the count, then send `preview: false` with that count as `estimated`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | The form's `form_key` (the `id` from `GET /forms`). |
+| `body` | `FormBackfillRequest` | yes | Request body; fields below. |
+
+Body fields (`FormBackfillRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.source_id` | `string` | yes | The site (write key) the form is installed on. min length 1, max length 500 |
+| `body.end_at` | `string (date-time) \| null` | no |  |
+| `body.estimated` | `integer` | no | The count a preview reported, echoed back. default `0`, min 0 |
+| `body.preview` | `boolean` | no | True reports what would be delivered without delivering it. default `true` |
+| `body.start_at` | `string (date-time) \| null` | no |  |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.forms.createFormBackfill({ path: { form_key: "example" }, body: { source_id: "id" } });
+```
+
+---
+
+<a id="op-createformgroup"></a>
+
+### `g8.api.forms.createFormGroup(input)`
+
+**Create Form Group**
+
+- HTTP: `POST /api/v1/forms/groups`
+- operationId: `create_form_group_forms_groups_post` (also callable as `g8.api.call("create_form_group_forms_groups_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `forms:write`
+
+Treat several inventory rows as one form.
+
+A member already in another group is MOVED here, not copied.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `FormGroupCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`FormGroupCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes | min length 1, max length 200 |
+| `body.form_type` | `"lead" \| "newsletter" \| "meeting" \| "contact" \| "download" \| "other" \| null` | no |  |
+| `body.members` | `Array<FormGroupMemberRef>` | no | max items 200 |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.createFormGroup({ body: { name: "Example" } });
+```
+
+---
+
+<a id="op-deleteformgroup"></a>
+
+### `g8.api.forms.deleteFormGroup(input)`
+
+**Delete Form Group**
+
+- HTTP: `DELETE /api/v1/forms/groups/{group_id}`
+- operationId: `delete_form_group_forms_groups__group_id__delete` (also callable as `g8.api.call("delete_form_group_forms_groups__group_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `forms:delete`
+
+Ungroup. The members return to standalone inventory rows; no submission is touched.
+
+The app answers 204 with no body; this answers the id that was removed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.group_id` | `string` | yes | The group's id. |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.forms.deleteFormGroup({ path: { group_id: "id" } });
+```
+
+---
+
+<a id="op-getformactivity"></a>
+
+### `g8.api.forms.getFormActivity(input)`
+
+**Get Form Activity**
+
+- HTTP: `GET /api/v1/forms/{form_key}/activity`
+- operationId: `get_form_activity_forms__form_key__activity_get` (also callable as `g8.api.call("get_form_activity_forms__form_key__activity_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+Recent submissions and what happened to each one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | Form key. |
+| `query.source_id` | `string` | yes | Which INSTALLED SOURCE of this form. Required: a form key can be present on more than one source, and every operation here is scoped to one. |
+
+**Returns** `ApiResponse_FormPayload_`: the envelope `{ data: FormPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.getFormActivity({ path: { form_key: "example" }, query: { source_id: "id" } });
+```
+
+---
+
+<a id="op-getformbackfill"></a>
+
+### `g8.api.forms.getFormBackfill(input)`
+
+**Get Form Backfill**
+
+- HTTP: `GET /api/v1/forms/{form_key}/backfills/{job_id}`
+- operationId: `get_form_backfill_forms__form_key__backfills__job_id__get` (also callable as `g8.api.call("get_form_backfill_forms__form_key__backfills__job_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+How a backfill is going, and what it delivered.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | The form's `form_key` (the `id` from `GET /forms`). |
+| `path.job_id` | `string` | yes | Job id from the backfill that started it. |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.getFormBackfill({ path: { form_key: "example", job_id: "id" } });
+```
+
+---
+
+<a id="op-getformfields"></a>
+
+### `g8.api.forms.getFormFields(input)`
+
+**Get Form Fields**
+
+- HTTP: `GET /api/v1/forms/{form_key}/fields`
+- operationId: `get_form_fields_forms__form_key__fields_get` (also callable as `g8.api.call("get_form_fields_forms__form_key__fields_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+The fields this form actually submits - what a mapping maps FROM.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | Form key. |
+| `query.source_id` | `string` | yes | Which INSTALLED SOURCE of this form. Required: a form key can be present on more than one source, and every operation here is scoped to one. |
+
+**Returns** `ApiResponse_FormPayload_`: the envelope `{ data: FormPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.getFormFields({ path: { form_key: "example" }, query: { source_id: "id" } });
+```
+
+---
+
+<a id="op-getformoverview"></a>
+
+### `g8.api.forms.getFormOverview(input)`
+
+**Get Form Overview**
+
+- HTTP: `GET /api/v1/forms/{form_key}/overview`
+- operationId: `get_form_overview_forms__form_key__overview_get` (also callable as `g8.api.call("get_form_overview_forms__form_key__overview_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+Per-form operational detail: health, submission metrics, destination.
+
+``source_id`` is required and comes from a ``list_forms`` result — a form
+id is only unique within its source.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | The form's HTML tag id / group key (from list_forms). |
+| `query.source_id` | `string` | yes | Write key / site the form belongs to (from list_forms). |
+
+**Returns** `ApiResponse_FormOverview_`: the envelope `{ data: FormOverview, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`FormOverview` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `form_key` | `string` | yes |  |
+| `source_id` | `string` | yes |  |
+| `activation_health` | `string \| null` | no |  |
+| `capture_health` | `string \| null` | no |  |
+| `delivery_health` | `string \| null` | no |  |
+| `display_name` | `string \| null` | no |  |
+| `identity_state` | `string \| null` | no |  |
+| `last_destination_verified_at` | `string (date-time) \| null` | no |  |
+| `metrics` | `Record<string, unknown>` | no |  |
+| `owner_id` | `string \| null` | no |  |
+| `placement_count` | `integer` | no | default `0` |
+| `recommended_action` | `string \| null` | no |  |
+| `technical_form_id` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.forms.getFormOverview({ path: { form_key: "example" }, query: { source_id: "id" } });
+```
+
+---
+
+<a id="op-getformplacements"></a>
+
+### `g8.api.forms.getFormPlacements(input)`
+
+**Get Form Placements**
+
+- HTTP: `GET /api/v1/forms/{form_key}/placements`
+- operationId: `get_form_placements_forms__form_key__placements_get` (also callable as `g8.api.call("get_form_placements_forms__form_key__placements_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+Where this form appears - the pages it has actually been seen on.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | Form key. |
+| `query.source_id` | `string` | yes | Which INSTALLED SOURCE of this form. Required: a form key can be present on more than one source, and every operation here is scoped to one. |
+
+**Returns** `ApiResponse_FormPayload_`: the envelope `{ data: FormPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.getFormPlacements({ path: { form_key: "example" }, query: { source_id: "id" } });
+```
+
+---
+
+<a id="op-getformpreview"></a>
+
+### `g8.api.forms.getFormPreview(input)`
+
+**Get Form Preview**
+
+- HTTP: `GET /api/v1/forms/{form_key}/preview/{preview_id}`
+- operationId: `get_form_preview_forms__form_key__preview__preview_id__get` (also callable as `g8.api.call("get_form_preview_forms__form_key__preview__preview_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+One placement preview: its state and, once captured, where the image is.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | The form's `form_key` (the `id` from `GET /forms`). |
+| `path.preview_id` | `string` | yes | Id from the capture that started it. |
+| `query.source_id` | `string` | yes | The site (write key) the form is installed on. |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.getFormPreview({
+  path: { form_key: "example", preview_id: "id" },
+  query: { source_id: "id" },
+});
+```
+
+---
+
+<a id="op-getformrouterecommendations"></a>
+
+### `g8.api.forms.getFormRouteRecommendations(input)`
+
+**Get Form Route Recommendations**
+
+- HTTP: `GET /api/v1/forms/{form_key}/route/recommendations`
+- operationId: `get_form_route_recommendations_forms__form_key__route_recommendations_get` (also callable as `g8.api.call("get_form_route_recommendations_forms__form_key__route_recommendations_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+Suggested field mappings for this form.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | Form key. |
+| `query.source_id` | `string` | yes | Which INSTALLED SOURCE of this form. Required: a form key can be present on more than one source, and every operation here is scoped to one. |
+| `query.target_list_id` | `integer \| null` | no | Destination list to tailor the mapping suggestions to. OPTIONAL on purpose: a caller asks for recommendations BEFORE choosing a destination, and making it required 422s every such request. |
+
+**Returns** `ApiResponse_FormPayload_`: the envelope `{ data: FormPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.getFormRouteRecommendations({ path: { form_key: "example" }, query: { source_id: "id" } });
+```
+
+---
+
+<a id="op-getformsubmissiontrace"></a>
+
+### `g8.api.forms.getFormSubmissionTrace(input)`
+
+**Get Form Submission Trace**
+
+- HTTP: `GET /api/v1/forms/{form_key}/submissions/{submission_id}/trace`
+- operationId: `get_form_submission_trace_forms__form_key__submissions__submission_id__trace_get` (also callable as `g8.api.call("get_form_submission_trace_forms__form_key__submissions__submission_id__trace_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+Follow ONE submission through the route, step by step.
+
+This is the endpoint that answers "the customer filled in the form, where
+did it go" - the question the whole surface exists for, and the one a
+rebuilt forms UI could not ask without it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | Form key. |
+| `path.submission_id` | `string` | yes | Submission id from the activity feed. |
+| `query.source_id` | `string` | yes | Which INSTALLED SOURCE of this form. Required: a form key can be present on more than one source, and every operation here is scoped to one. |
+
+**Returns** `ApiResponse_FormPayload_`: the envelope `{ data: FormPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.getFormSubmissionTrace({
+  path: { form_key: "example", submission_id: "id" },
+  query: { source_id: "id" },
+});
+```
+
+---
+
+<a id="op-getsiteaudit"></a>
+
+### `g8.api.forms.getSiteAudit(input?)`
+
+**Get Site Audit**
+
+- HTTP: `GET /api/v1/forms/site-audit`
+- operationId: `get_site_audit_forms_site_audit_get` (also callable as `g8.api.call("get_site_audit_forms_site_audit_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+Findings from the last crawl: forms on the site that are not being captured.
+
+**Input**: none.
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.getSiteAudit();
+```
+
+---
+
+<a id="op-listformgroups"></a>
+
+### `g8.api.forms.listFormGroups(input?)`
+
+**List Form Groups**
+
+- HTTP: `GET /api/v1/forms/groups`
+- operationId: `list_form_groups_forms_groups_get` (also callable as `g8.api.call("list_form_groups_forms_groups_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+Curated groups - several inventory rows treated as one form - with their members.
+
+**Input**: none.
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.listFormGroups();
+```
+
+---
+
+<a id="op-listforms"></a>
+
+### `g8.api.forms.listForms(input?)`
+
+**List Forms**
+
+- HTTP: `GET /api/v1/forms`
+- operationId: `list_forms_forms_get` (also callable as `g8.api.call("list_forms_forms_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+List and search the org's lead-capture forms.
+
+Use ``search`` to find a specific form by name (e.g. "discovery"). Each
+item carries the ``source_id`` and ``form_key`` needed for the overview
+endpoint.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.page` | `integer` | no | 1-indexed page. default `1` |
+| `query.per_page` | `integer` | no | Rows per page (max 200). default `20` |
+| `query.search` | `string \| null` | no | Case-insensitive substring match on form name/id. |
+| `query.source_id` | `string \| null` | no | Filter to a single write key / site. |
+| `query.sort_field` | `"submissions_30d" \| "total_submissions" \| "latest_submitted_at" \| "form_tag_id" \| null` | no | total_submissions \| latest_submitted_at \| form_tag_id |
+| `query.sort_order` | `"asc" \| "desc" \| null` | no | asc \| desc |
+
+**Returns** `ApiResponse_FormsListResponse_`: the envelope `{ data: FormsListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`FormsListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<FormSummary>` | no |  |
+| `page` | `integer` | no | default `1` |
+| `per_page` | `integer` | no | default `20` |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.forms.listForms();
+```
+
+---
+
+<a id="op-listsavedformviews"></a>
+
+### `g8.api.forms.listSavedFormViews(input?)`
+
+**List Saved Form Views**
+
+- HTTP: `GET /api/v1/forms/views/saved`
+- operationId: `list_saved_form_views_forms_views_saved_get` (also callable as `g8.api.call("list_saved_form_views_forms_views_saved_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+Saved filter sets over the form inventory, as `items`.
+
+**Input**: none.
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.listSavedFormViews();
+```
+
+---
+
+<a id="op-pauseformdelivery"></a>
+
+### `g8.api.forms.pauseFormDelivery(input)`
+
+**Pause Form Delivery**
+
+- HTTP: `POST /api/v1/forms/{form_key}/delivery/pause`
+- operationId: `pause_form_delivery_forms__form_key__delivery_pause_post` (also callable as `g8.api.call("pause_form_delivery_forms__form_key__delivery_pause_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `forms:run`
+
+Stop delivering this form's submissions.
+
+The form keeps ACCEPTING submissions - pausing stops them being routed
+onward, it does not take the form down. They queue rather than vanish.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | Form key. |
+| `body` | `FormSourceScopedRequest` | yes | Request body; fields below. |
+
+Body fields (`FormSourceScopedRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.source_id` | `string` | yes | min length 1, max length 500 |
+
+**Returns** `ApiResponse_FormPayload_`: the envelope `{ data: FormPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.forms.pauseFormDelivery({ path: { form_key: "example" }, body: { source_id: "id" } });
+```
+
+---
+
+<a id="op-previewformmapping"></a>
+
+### `g8.api.forms.previewFormMapping(input)`
+
+**Preview Form Mapping**
+
+- HTTP: `POST /api/v1/forms/{form_key}/mapping/preview`
+- operationId: `preview_form_mapping_forms__form_key__mapping_preview_post` (also callable as `g8.api.call("preview_form_mapping_forms__form_key__mapping_preview_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+What submissions would look like under a mapping, WITHOUT saving it.
+
+Nothing is written and no list is filled. Same PII rule as the submissions read.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | The form's `form_key` (the `id` from `GET /forms`). |
+| `body` | `FormMappingRequest` | yes | Request body; fields below. |
+
+Body fields (`FormMappingRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.target_list_name` | `string` | yes | Name of the list the mapped submissions are saved to. |
+| `body.expected_route_version` | `integer \| null` | no | Optimistic-concurrency guard: the route version you last read. Omit for last-writer-wins. min 1 |
+| `body.form_to_contact_field_mapping` | `Array<FormFieldMapping>` | no | Submitted field -> contact field. |
+| `body.source_id` | `string \| null` | no | min length 1, max length 500 |
+| `body.submissions_page` | `integer` | no | default `1`, min 1 |
+| `body.submissions_per_page` | `integer` | no | default `20`, min 1 |
+| `body.target_list_id` | `integer \| null` | no | Id of that list, when it already exists. min 1 |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.previewFormMapping({
+  path: { form_key: "example" },
+  body: { target_list_name: "Example" },
+});
+```
+
+---
+
+<a id="op-previewunidentifiedgrouping"></a>
+
+### `g8.api.forms.previewUnidentifiedGrouping(input?)`
+
+**Preview Unidentified Grouping**
+
+- HTTP: `GET /api/v1/forms/unidentified/grouping`
+- operationId: `preview_unidentified_grouping_forms_unidentified_grouping_get` (also callable as `g8.api.call("preview_unidentified_grouping_forms_unidentified_grouping_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+How submissions with no form id WOULD split under each grouping axis.
+
+Some sites render forms with no stable id, so every such submission lands
+in one bucket. Each option carries the numbers behind it, including whether
+it would split one real form apart or merge several together.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.source_id` | `string \| null` | no | One site. Omit for every site. |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.previewUnidentifiedGrouping();
+```
+
+---
+
+<a id="op-removeformgroupmembers"></a>
+
+### `g8.api.forms.removeFormGroupMembers(input)`
+
+**Remove Form Group Members**
+
+- HTTP: `POST /api/v1/forms/groups/{group_id}/members/remove`
+- operationId: `remove_form_group_members_forms_groups__group_id__members_remove_post` (also callable as `g8.api.call("remove_form_group_members_forms_groups__group_id__members_remove_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `forms:write`
+
+Remove inventory rows from a group.
+
+POST rather than DELETE because it names a SET in a body, and enough
+proxies strip a DELETE body to make removal silently remove nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.group_id` | `string` | yes | The group's id. |
+| `body` | `FormGroupMembersRequest` | yes | Request body; fields below. |
+
+Body fields (`FormGroupMembersRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.members` | `Array<FormGroupMemberRef>` | yes | min items 1, max items 200 |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.removeFormGroupMembers({
+  path: { group_id: "id" },
+  body: { members: [{ form_key: "example", source_id: "id" }] },
+});
+```
+
+---
+
+<a id="op-requestsiteauditscan"></a>
+
+### `g8.api.forms.requestSiteAuditScan(input?)`
+
+**Request Site Audit Scan**
+
+- HTTP: `POST /api/v1/forms/site-audit/scan`
+- operationId: `request_site_audit_scan_forms_site_audit_scan_post` (also callable as `g8.api.call("request_site_audit_scan_forms_site_audit_scan_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `forms:write`
+
+Crawl the site again. ASYNCHRONOUS; read `GET /forms/site-audit` afterwards.
+
+At most one enqueue per org per minute: inside that window the answer is
+`already_queued` and nothing new is started.
+
+**Input**: none.
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.requestSiteAuditScan();
+```
+
+---
+
+<a id="op-resumeformdelivery"></a>
+
+### `g8.api.forms.resumeFormDelivery(input)`
+
+**Resume Form Delivery**
+
+- HTTP: `POST /api/v1/forms/{form_key}/delivery/resume`
+- operationId: `resume_form_delivery_forms__form_key__delivery_resume_post` (also callable as `g8.api.call("resume_form_delivery_forms__form_key__delivery_resume_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `forms:run`
+
+Start delivering again.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | Form key. |
+| `body` | `FormSourceScopedRequest` | yes | Request body; fields below. |
+
+Body fields (`FormSourceScopedRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.source_id` | `string` | yes | min length 1, max length 500 |
+
+**Returns** `ApiResponse_FormPayload_`: the envelope `{ data: FormPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.forms.resumeFormDelivery({ path: { form_key: "example" }, body: { source_id: "id" } });
+```
+
+---
+
+<a id="op-retryformdelivery"></a>
+
+### `g8.api.forms.retryFormDelivery(input)`
+
+**Retry Form Delivery**
+
+- HTTP: `POST /api/v1/forms/deliveries/{receipt_id}/retry`
+- operationId: `retry_form_delivery_forms_deliveries__receipt_id__retry_post` (also callable as `g8.api.call("retry_form_delivery_forms_deliveries__receipt_id__retry_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `forms:run`
+
+Retry ONE failed delivery.
+
+Scoped by receipt rather than by form, so a caller retries the specific
+submission that failed instead of replaying everything - which is what the
+backfill endpoints are for, and why they are not on this surface.
+
+NOTE ON ROUTING ORDER: `/forms/deliveries/...` is a LITERAL first segment
+that `/forms/{form_key}/...` would otherwise swallow, reading "deliveries"
+as a form key. It is declared here, and the shadowing test compares
+compiled match patterns to keep it that way.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.receipt_id` | `string` | yes | Delivery receipt id from the activity feed. |
+
+**Returns** `ApiResponse_FormPayload_`: the envelope `{ data: FormPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.forms.retryFormDelivery({ path: { receipt_id: "id" } });
+```
+
+---
+
+<a id="op-rollbackformroute"></a>
+
+### `g8.api.forms.rollbackFormRoute(input)`
+
+**Rollback Form Route**
+
+- HTTP: `DELETE /api/v1/forms/{form_key}/route`
+- operationId: `rollback_form_route_forms__form_key__route_delete` (also callable as `g8.api.call("rollback_form_route_forms__form_key__route_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `forms:delete`
+
+Roll the route back, or cancel a pending one.
+
+A DELETE that takes a BODY, matching the app - because this is not "delete
+the route", it is "move it back", and which version to move to has to
+travel with the request. The form keeps routing; it routes as it did
+before.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | Form key. |
+| `body` | `FormRouteRollbackRequest` | yes | Request body; fields below. |
+
+Body fields (`FormRouteRollbackRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.source_id` | `string` | yes | min length 1, max length 500 |
+| `body.cancel_current` | `boolean` | no | Cancel a pending route instead of restoring an old one. default `false` |
+| `body.expected_current_version` | `integer \| null` | no | PRECONDITION: the version you believe is live. Guards a concurrent rollback. min 1 |
+| `body.restore_version` | `integer \| null` | no | Version to restore. Omit to take the previous one. min 1 |
+
+**Returns** `ApiResponse_FormPayload_`: the envelope `{ data: FormPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.forms.rollbackFormRoute({ path: { form_key: "example" }, body: { source_id: "id" } });
+```
+
+---
+
+<a id="op-saveformmapping"></a>
+
+### `g8.api.forms.saveFormMapping(input)`
+
+**Save Form Mapping**
+
+- HTTP: `POST /api/v1/forms/{form_key}/mapping/save`
+- operationId: `save_form_mapping_forms__form_key__mapping_save_post` (also callable as `g8.api.call("save_form_mapping_forms__form_key__mapping_save_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `forms:write`
+
+Save how a form's submitted fields become contact fields.
+
+A FULL REPLACEMENT of the mapping. Everything captured from now on lands
+according to it, so preview first. `expected_route_version` makes it a
+conditional write (409 when someone else saved in between).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | The form's `form_key` (the `id` from `GET /forms`). |
+| `body` | `FormMappingRequest` | yes | Request body; fields below. |
+
+Body fields (`FormMappingRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.target_list_name` | `string` | yes | Name of the list the mapped submissions are saved to. |
+| `body.expected_route_version` | `integer \| null` | no | Optimistic-concurrency guard: the route version you last read. Omit for last-writer-wins. min 1 |
+| `body.form_to_contact_field_mapping` | `Array<FormFieldMapping>` | no | Submitted field -> contact field. |
+| `body.source_id` | `string \| null` | no | min length 1, max length 500 |
+| `body.submissions_page` | `integer` | no | default `1`, min 1 |
+| `body.submissions_per_page` | `integer` | no | default `20`, min 1 |
+| `body.target_list_id` | `integer \| null` | no | Id of that list, when it already exists. min 1 |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.saveFormMapping({
+  path: { form_key: "example" },
+  body: { target_list_name: "Example" },
+});
+```
+
+---
+
+<a id="op-saveformroute"></a>
+
+### `g8.api.forms.saveFormRoute(input)`
+
+**Save Form Route**
+
+- HTTP: `PUT /api/v1/forms/{form_key}/route`
+- operationId: `save_form_route_forms__form_key__route_put` (also callable as `g8.api.call("save_form_route_forms__form_key__route_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `forms:write`
+
+Set where this form's submissions go, and how its fields map.
+
+SEND THE `expected_*` PRECONDITIONS. They are optimistic-concurrency
+guards, not settings: without them the save is last-writer-wins and can
+silently overwrite a colleague's route on a live form.
+
+`workflow_policy` defaults to `disabled`. `simulate` records what WOULD
+have run without running it, which is the safe way to turn automation on
+for a form that is already receiving real submissions.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | Form key. |
+| `body` | `FormRouteRequest` | yes | Request body; fields below. |
+
+Body fields (`FormRouteRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.source_id` | `string` | yes | min length 1, max length 500 |
+| `body.target_list_id` | `integer` | yes | Audience list submissions land in. min 1 |
+| `body.defaults` | `Record<string, unknown>` | no | Values applied to every submission. |
+| `body.expected_current_route_version` | `integer \| null` | no | PRECONDITION. The route version you are replacing. Without it the save is last-writer-wins and can silently overwrite a colleague's route. min 0 |
+| `body.expected_route_history_version` | `integer \| null` | no | PRECONDITION on the route's history log. min 0 |
+| `body.expected_schema_version` | `integer \| null` | no | PRECONDITION, not a setting. The form schema version this mapping was built against; the save is rejected if the form has changed shape since. Omitting it saves a mapping against a schema you have not seen. min 1 |
+| `body.mapping` | `Array<Record<string, unknown>>` | no | Form field -> graph8 field. |
+| `body.schema_drift_approved` | `boolean` | no | Save anyway when the schema HAS drifted. Deliberate override. default `false` |
+| `body.workflow_policy` | `"disabled" \| "simulate" \| "enabled"` | no | Whether routed submissions trigger workflows. `simulate` records what WOULD have run without running it - the safe way to turn automation on for a live form. Defaults to `disabled`. default `"disabled"` |
+
+**Returns** `ApiResponse_FormPayload_`: the envelope `{ data: FormPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.saveFormRoute({
+  path: { form_key: "example" },
+  body: { source_id: "id", target_list_id: 1 },
+});
+```
+
+---
+
+<a id="op-saveformview"></a>
+
+### `g8.api.forms.saveFormView(input)`
+
+**Save Form View**
+
+- HTTP: `PUT /api/v1/forms/views/saved/{view_id}`
+- operationId: `save_form_view_forms_views_saved__view_id__put` (also callable as `g8.api.call("save_form_view_forms_views_saved__view_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `forms:write`
+
+Create or replace a saved view. PUT because it is an upsert by id.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.view_id` | `string` | yes | The view's id. Created when it does not exist. |
+| `body` | `FormSavedViewRequest` | yes | Request body; fields below. |
+
+Body fields (`FormSavedViewRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.filters` | `FormInventoryFilters` | yes |  |
+| `body.name` | `string` | yes | min length 1, max length 100 |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.saveFormView({ path: { view_id: "id" }, body: { filters: {}, name: "Example" } });
+```
+
+---
+
+<a id="op-searchformsubmissions"></a>
+
+### `g8.api.forms.searchFormSubmissions(input)`
+
+**Search Form Submissions**
+
+- HTTP: `POST /api/v1/forms/{form_key}/submissions`
+- operationId: `search_form_submissions_forms__form_key__submissions_post` (also callable as `g8.api.call("search_form_submissions_forms__form_key__submissions_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `forms:read`
+
+What people actually submitted to one form.
+
+A paginated READ; POST only because the filter set is a body. Identifying
+fields are REDACTED for a key without the Signals write capability, exactly
+as in the browser - an empty-looking value is a redaction, not a missing
+submission.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | The form's `form_key` (the `id` from `GET /forms`). |
+| `body` | `FormSubmissionsSearchRequest` | yes | Request body; fields below. |
+
+Body fields (`FormSubmissionsSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.conditions` | `Array<FormSubmissionCondition>` | no |  |
+| `body.page` | `integer` | no | default `1`, min 1 |
+| `body.per_page` | `integer` | no | default `20`, min 1 |
+| `body.source_id` | `string \| null` | no | One site. Omit for every site the form is on. max length 500 |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.searchFormSubmissions({ path: { form_key: "example" }, body: {} });
+```
+
+---
+
+<a id="op-setunidentifiedgrouping"></a>
+
+### `g8.api.forms.setUnidentifiedGrouping(input)`
+
+**Set Unidentified Grouping**
+
+- HTTP: `PUT /api/v1/forms/unidentified/grouping`
+- operationId: `set_unidentified_grouping_forms_unidentified_grouping_put` (also callable as `g8.api.call("set_unidentified_grouping_forms_unidentified_grouping_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `forms:write`
+
+Choose how one site's id-less submissions are split into forms.
+
+Applied at read time, so it regroups HISTORY as well as new traffic: the
+shape of the inventory changes under anything already pointed at it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `FormGroupingRuleRequest` | yes | Request body; fields below. |
+
+Body fields (`FormGroupingRuleRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.source_id` | `string` | yes | max length 500 |
+| `body.axis` | `"none" \| "fields" \| "component" \| "page" \| "campaign" \| "source_attribute"` | no | default `"none"` |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.setUnidentifiedGrouping({ body: { source_id: "id" } });
+```
+
+---
+
+<a id="op-syncunidentifiedgroup"></a>
+
+### `g8.api.forms.syncUnidentifiedGroup(input)`
+
+**Sync Unidentified Group**
+
+- HTTP: `POST /api/v1/forms/unidentified/groups/sync`
+- operationId: `sync_unidentified_group_forms_unidentified_groups_sync_post` (also callable as `g8.api.call("sync_unidentified_group_forms_unidentified_groups_sync_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `forms:write`
+
+Name one group of id-less submissions and fill a list with its leads.
+
+Writes EVERY matching submission to `target_list_id` before answering;
+`submissions_synced` is the number actually written. Gated twice, as the
+app gates it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `FormGroupSyncRequest` | yes | Request body; fields below. |
+
+Body fields (`FormGroupSyncRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.axis` | `"fields" \| "component" \| "page" \| "campaign" \| "source_attribute"` | yes |  |
+| `body.group_id` | `string` | yes | min length 1, max length 200 |
+| `body.source_id` | `string` | yes | max length 500 |
+| `body.matcher` | `string` | no | The axis value this group covers. default `""`, max length 2000 |
+| `body.name` | `string` | no | default `""`, max length 200 |
+| `body.target_list_id` | `integer \| null` | no | min 1 |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.syncUnidentifiedGroup({ body: { axis: "fields", group_id: "id", source_id: "id" } });
+```
+
+---
+
+<a id="op-testformroute"></a>
+
+### `g8.api.forms.testFormRoute(input)`
+
+**Test Form Route**
+
+- HTTP: `POST /api/v1/forms/{form_key}/route/test`
+- operationId: `test_form_route_forms__form_key__route_test_post` (also callable as `g8.api.call("test_form_route_forms__form_key__route_test_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `forms:write`
+
+Run a test submission through the route and report where it landed.
+
+Gated on LISTS WRITE, not read, because it exercises the delivery path.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | Form key. |
+| `body` | `FormSourceScopedRequest` | yes | Request body; fields below. |
+
+Body fields (`FormSourceScopedRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.source_id` | `string` | yes | min length 1, max length 500 |
+
+**Returns** `ApiResponse_FormPayload_`: the envelope `{ data: FormPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.testFormRoute({ path: { form_key: "example" }, body: { source_id: "id" } });
+```
+
+---
+
+<a id="op-updateformgroup"></a>
+
+### `g8.api.forms.updateFormGroup(input)`
+
+**Update Form Group**
+
+- HTTP: `PATCH /api/v1/forms/groups/{group_id}`
+- operationId: `update_form_group_forms_groups__group_id__patch` (also callable as `g8.api.call("update_form_group_forms_groups__group_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `forms:write`
+
+Rename or re-type a group. Membership changes through the member routes.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.group_id` | `string` | yes | The group's id. |
+| `body` | `FormGroupPatchRequest` | yes | Request body; fields below. |
+
+Body fields (`FormGroupPatchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.form_type` | `"lead" \| "newsletter" \| "meeting" \| "contact" \| "download" \| "other" \| null` | no |  |
+| `body.name` | `string \| null` | no | min length 1, max length 200 |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.updateFormGroup({ path: { group_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updateformregistry"></a>
+
+### `g8.api.forms.updateFormRegistry(input)`
+
+**Update Form Registry**
+
+- HTTP: `PATCH /api/v1/forms/{form_key}`
+- operationId: `update_form_registry_forms__form_key__patch` (also callable as `g8.api.call("update_form_registry_forms__form_key__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `forms:write`
+
+Rename a form, reassign its owner, or archive it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.form_key` | `string` | yes | Form key. |
+| `body` | `FormRegistryPatchRequest` | yes | Request body; fields below. |
+
+Body fields (`FormRegistryPatchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.source_id` | `string` | yes | Which INSTALLED SOURCE of this form. A form key can be present on more than one source, and every operation on this surface is scoped to one - omitting it would silently act on whichever the backend picked. min length 1, max length 500 |
+| `body.archived` | `boolean \| null` | no | Archive or unarchive. Omit to leave unchanged. |
+| `body.display_name` | `string \| null` | no | min length 1, max length 200 |
+| `body.owner_id` | `string \| null` | no | max length 200 |
+
+**Returns** `ApiResponse_FormPayload_`: the envelope `{ data: FormPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.updateFormRegistry({ path: { form_key: "example" }, body: { source_id: "id" } });
+```
+
+---
+
+<a id="op-updatesiteauditfinding"></a>
+
+### `g8.api.forms.updateSiteAuditFinding(input)`
+
+**Update Site Audit Finding**
+
+- HTTP: `PATCH /api/v1/forms/site-audit/findings/{finding_id}`
+- operationId: `update_site_audit_finding_forms_site_audit_findings__finding_id__patch` (also callable as `g8.api.call("update_site_audit_finding_forms_site_audit_findings__finding_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `forms:write`
+
+Triage one finding. `ignored` keeps it out of future reports without resolving it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.finding_id` | `string` | yes | The finding's id. |
+| `body` | `FormSiteAuditStatusRequest` | yes | Request body; fields below. |
+
+Body fields (`FormSiteAuditStatusRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.status` | `"open" \| "acknowledged" \| "ignored" \| "resolved"` | yes |  |
+
+**Returns** `ApiResponse_FormsAdminPayload_`: the envelope `{ data: FormsAdminPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.forms.updateSiteAuditFinding({ path: { finding_id: "id" }, body: { status: "open" } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-formfieldmapping"></a>
+
+### `FormFieldMapping`
+
+One submitted field and the contact field it lands in. Mirrors `MappedFieldName`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `source_field` | `string` | yes | Name of the submitted form field. |
+| `target_field` | `string` | yes | Contact field it is written to. |
+| `dynamic_column_id` | `integer \| null` | no | Id of that dynamic column. |
+| `is_new_column` | `boolean` | no | Whether `target_field` is a dynamic column created by this mapping. default `false` |
+| `new_column_name` | `string \| null` | no | Display name of that dynamic column. |
+| `static_value` | `string \| null` | no | Constant written to `target_field` instead of reading a submitted field. |
+
+<a id="type-formgroupmemberref"></a>
+
+### `FormGroupMemberRef`
+
+One inventory row in a curated group. Mirrors `GroupMemberRefRequest`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `form_key` | `string` | yes | min length 1, max length 500 |
+| `source_id` | `string` | yes | Write key, or its bare key id. min length 1, max length 500 |
+
+<a id="type-forminventoryfilters"></a>
+
+### `FormInventoryFilters`
+
+The inventory filter set a saved view stores. Mirrors `PaginationRequest`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `activity_end` | `string (date-time) \| null` | no |  |
+| `activity_start` | `string (date-time) \| null` | no |  |
+| `capture_health` | `"healthy" \| "no_data" \| null` | no |  |
+| `delivery_state` | `"active" \| "paused" \| "failed" \| "not_configured" \| null` | no |  |
+| `destination_list_id` | `integer \| null` | no | min 1 |
+| `has_failures` | `boolean \| null` | no |  |
+| `has_new_fields` | `boolean \| null` | no |  |
+| `identity_quality` | `"verified" \| "variant" \| "collision" \| "historic_uncertain" \| null` | no |  |
+| `mapping_state` | `"mapped" \| "unmapped" \| null` | no |  |
+| `owner_id` | `string \| null` | no | max length 200 |
+| `page` | `integer` | no | default `1`, min 1 |
+| `per_page` | `integer` | no | default `20`, min 1 |
+| `saved_view` | `"live" \| "needs_setup" \| "failing" \| "ignored" \| "healthy" \| "failures" \| "new_fields" \| "no_recent_submissions" \| … \| null` | no |  |
+| `search` | `string \| null` | no | max length 200 |
+| `sort_field` | `"submissions_30d" \| "total_submissions" \| "latest_submitted_at" \| "form_tag_id" \| null` | no |  |
+| `sort_order` | `"asc" \| "desc" \| null` | no |  |
+| `source_id` | `string \| null` | no | max length 500 |
+| `write_key` | `string \| null` | no |  |
+
+<a id="type-formsubmissioncondition"></a>
+
+### `FormSubmissionCondition`
+
+One filter over a form's submissions. Mirrors the app's `ConditionRequest`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `field` | `string` | yes | Submitted field name, or a submission attribute. |
+| `operator` | `string` | yes | Comparison operator, in the app's filter grammar. |
+| `value` | `unknown` | yes | Value compared against. |
+| `value_to` | `unknown` | no | Upper bound, for range operators. |
+
+<a id="type-formsummary"></a>
+
+### `FormSummary`
+
+One lead-capture form as returned by the list/search endpoint.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes | The form's HTML tag id (or the id-less group key). |
+| `display_name` | `string \| null` | no | Human-friendly name for the form. |
+| `form_key` | `string \| null` | no | Alias for id; the addressable key for detail lookups. |
+| `latest_submitted_at` | `string (date-time) \| null` | no | Most recent submission timestamp. |
+| `page_url` | `string \| null` | no | URL of a page where the form was submitted. |
+| `source_id` | `string \| null` | no | Write key / site the form was submitted from. |
+| `target_list_id` | `integer \| null` | no | Destination list id, if the form is routed. |
+| `target_list_name` | `string \| null` | no | Destination list name, if the form is routed. |
+| `total_submissions` | `integer` | no | Total submissions received for this form. default `0` |