@graph8/sdk 0.245.0 → 0.260.0

package/docs/api/lists.md

@@ -0,0 +1,1609 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.lists`: Lists
+
+36 operations (12 read, 18 write, 6 destructive).
+
+6 of these also have a hand-written method (`g8.lists`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+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: [lists.d.ts](lists.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`addContactsToList`](#op-addcontactstolist) ★ | `POST /api/v1/lists/{list_id}/contacts` | write | `lists:write` | Add Contacts To List |
+| [`addDealsToList`](#op-adddealstolist) | `POST /api/v1/lists/{audience_id}/deals` | write | `lists:write` | Add Deals To List |
+| [`assignListToFolder`](#op-assignlisttofolder) | `PUT /api/v1/lists/folders/assignments/{audience_id}` | write | `lists:write` | Assign List To Folder |
+| [`assignListsToFolder`](#op-assignliststofolder) | `PUT /api/v1/lists/folders/assignments` | write | `lists:write` | Assign Lists To Folder |
+| [`checkListIntegrity`](#op-checklistintegrity) | `POST /api/v1/lists/{list_id}/integrity-check` | read | `lists:read` | Check List Integrity |
+| [`createEmptyList`](#op-createemptylist) | `POST /api/v1/lists/create-empty` | write | `lists:write` | Create Empty List |
+| [`createList`](#op-createlist) ★ | `POST /api/v1/lists` | write | `lists:write` | Create List |
+| [`createListFolder`](#op-createlistfolder) | `POST /api/v1/lists/folders` | write | `lists:write` | Create List Folder |
+| [`createMasterList`](#op-createmasterlist) | `POST /api/v1/lists/masters` | write | `lists:write` | Create Master List |
+| [`deleteCompaniesFromList`](#op-deletecompaniesfromlist) | `DELETE /api/v1/lists/{audience_id}/companies` | destructive | `lists:delete` | Delete Companies From List |
+| [`deleteLeadsFromList`](#op-deleteleadsfromlist) | `DELETE /api/v1/lists/{audience_id}/leads` | destructive | `lists:delete` | Delete Leads From List |
+| [`deleteList`](#op-deletelist) ★ | `DELETE /api/v1/lists/{list_id}` | destructive | `lists:delete` | Delete List |
+| [`deleteListFolder`](#op-deletelistfolder) | `DELETE /api/v1/lists/folders/{folder_id}` | destructive | `lists:delete` | Delete List Folder |
+| [`deleteSuppressionsFromList`](#op-deletesuppressionsfromlist) | `DELETE /api/v1/lists/{audience_id}/suppressions` | destructive | `lists:delete` | Delete Suppressions From List |
+| [`downloadList`](#op-downloadlist) | `GET /api/v1/lists/{audience_id}/download` | read | `lists:read` | Download List |
+| [`generateTrackedLinks`](#op-generatetrackedlinks) | `POST /api/v1/lists/{audience_id}/generate-tracked-links` | write | `lists:write` | Generate Tracked Links |
+| [`getListColumnCapabilities`](#op-getlistcolumncapabilities) | `GET /api/v1/lists/{audience_id}/column-capabilities` | read | `lists:read` | Get List Column Capabilities |
+| [`getListContacts`](#op-getlistcontacts) ★ | `GET /api/v1/lists/{list_id}/contacts` | read | `lists:read` | Get List Contacts |
+| [`getListKeywordLinks`](#op-getlistkeywordlinks) | `GET /api/v1/lists/{audience_id}/keyword-links` | read | `lists:read` | Get List Keyword Links |
+| [`getListPerformance`](#op-getlistperformance) | `GET /api/v1/lists/performance` | read | `lists:read` | Get List Performance |
+| [`getTrackedLinkColumns`](#op-gettrackedlinkcolumns) | `GET /api/v1/lists/{audience_id}/tracked-links/columns` | read | `lists:read` | Get Tracked Link Columns |
+| [`listDataColumns`](#op-listdatacolumns) | `GET /api/v1/lists/{list_id}/data-columns` | read | `lists:read` | List Data Columns |
+| [`listListFolders`](#op-listlistfolders) | `GET /api/v1/lists/folders` | read | `lists:read` | List List Folders |
+| [`listLists`](#op-listlists) ★ | `GET /api/v1/lists` | read | `lists:read` | List Lists |
+| [`listMasterLists`](#op-listmasterlists) | `GET /api/v1/lists/masters` | read | `lists:read` | List Master Lists |
+| [`patchDynamicValue`](#op-patchdynamicvalue) | `PATCH /api/v1/lists/{audience_id}/dynamic-value` | write | `lists:write` | Patch Dynamic Value |
+| [`previewListOwnerTransfer`](#op-previewlistownertransfer) | `GET /api/v1/lists/{audience_id}/owner/preview` | read | `lists:read` | Preview List Owner Transfer |
+| [`reassignListOwner`](#op-reassignlistowner) | `PATCH /api/v1/lists/{audience_id}/owner` | write | `lists:write` | Reassign List Owner |
+| [`recordListOpened`](#op-recordlistopened) | `POST /api/v1/lists/folders/activity/{audience_id}` | write | `lists:write` | Record List Opened |
+| [`refreshDynamicList`](#op-refreshdynamiclist) | `POST /api/v1/lists/{audience_id}/refresh` | write | `lists:write` | Refresh Dynamic List |
+| [`refreshMasterListNow`](#op-refreshmasterlistnow) | `POST /api/v1/lists/{audience_id}/master-refresh` | write | `lists:write` | Refresh Master List Now |
+| [`removeContactsFromList`](#op-removecontactsfromlist) ★ | `DELETE /api/v1/lists/{list_id}/contacts` | destructive | `lists:delete` | Remove Contacts From List |
+| [`starList`](#op-starlist) | `PUT /api/v1/lists/folders/stars/{audience_id}` | write | `lists:write` | Star List |
+| [`updateList`](#op-updatelist) | `PATCH /api/v1/lists/{list_id}` | write | `lists:write` | Update List |
+| [`updateListFolder`](#op-updatelistfolder) | `PATCH /api/v1/lists/folders/{folder_id}` | write | `lists:write` | Update List Folder |
+| [`updateMasterListConfig`](#op-updatemasterlistconfig) | `PATCH /api/v1/lists/{audience_id}/master-config` | write | `lists:write` | Update Master List Config |
+
+---
+
+<a id="op-addcontactstolist"></a>
+
+### `g8.api.lists.addContactsToList(input)`
+
+**Add Contacts To List**
+
+- HTTP: `POST /api/v1/lists/{list_id}/contacts`
+- operationId: `add_contacts_to_list_lists__list_id__contacts_post` (also callable as `g8.api.call("add_contacts_to_list_lists__list_id__contacts_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+- ★ Hand-written: [`g8.lists.addContacts()`](../sdk-clients.md#g8-lists-addcontacts)
+
+Add contacts to a list by their IDs.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.list_id` | `integer` | yes | List ID |
+| `body` | `AddContactsToListRequest` | yes | Request body; fields below. |
+
+Body fields (`AddContactsToListRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.contact_ids` | `Array<integer>` | yes | List of contact IDs to add |
+| `body.conflict_resolution` | `"add_all" \| "skip_all" \| "custom" \| null` | no | Required on retry after a 409 CONFLICT_REVIEW_REQUIRED response: 'add_all' adds ready + every warned contact, 'skip_all' adds only ready contacts, 'custom' adds ready + the ids in include_warned_ids. Blocked contacts are always excluded regardless of this value. |
+| `body.include_warned_ids` | `Array<string> \| null` | no | With conflict_resolution='custom', the warned contact ids to also add. |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.lists.addContactsToList({ path: { list_id: 123 }, body: { contact_ids: [123] } });
+```
+
+---
+
+<a id="op-adddealstolist"></a>
+
+### `g8.api.lists.addDealsToList(input)`
+
+**Add Deals To List**
+
+- HTTP: `POST /api/v1/lists/{audience_id}/deals`
+- operationId: `add_deals_to_list_lists__audience_id__deals_post` (also callable as `g8.api.call("add_deals_to_list_lists__audience_id__deals_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Put deals on a deals list.
+
+Each deal is checked against the caller's DEAL scope as well as the list's,
+so adding a deal you cannot see is refused rather than silently skipped.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | List (audience) id. |
+| `body` | `AddDealsToListRequest` | yes | Request body; fields below. |
+
+Body fields (`AddDealsToListRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.deal_ids` | `Array<string>` | yes | Deal ids (strings, unlike the others). |
+| `body.source` | `string \| null` | no | Where the addition came from, for the audit trail. |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.lists.addDealsToList({ path: { audience_id: 123 }, body: { deal_ids: ["id"] } });
+```
+
+---
+
+<a id="op-assignlisttofolder"></a>
+
+### `g8.api.lists.assignListToFolder(input)`
+
+**Assign List To Folder**
+
+- HTTP: `PUT /api/v1/lists/folders/assignments/{audience_id}`
+- operationId: `assign_list_to_folder_lists_folders_assignments__audience_id__put` (also callable as `g8.api.call("assign_list_to_folder_lists_folders_assignments__audience_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+File one list into a folder, or out of every folder. FREE.
+
+Requires WRITE access to the list, as in the app. `folder_id` null unfiles
+it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes |  |
+| `body` | `ListFolderAssignRequest` | yes | Request body; fields below. |
+
+Body fields (`ListFolderAssignRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.folder_id` | `string (uuid) \| null` | no | The folder. Null takes the list OUT of every folder. |
+
+**Returns**: no JSON body is declared for the success response.
+
+**Example**
+
+```ts
+const result = await g8.api.lists.assignListToFolder({ path: { audience_id: 123 }, body: {} });
+```
+
+---
+
+<a id="op-assignliststofolder"></a>
+
+### `g8.api.lists.assignListsToFolder(input)`
+
+**Assign Lists To Folder**
+
+- HTTP: `PUT /api/v1/lists/folders/assignments`
+- operationId: `assign_lists_to_folder_lists_folders_assignments_put` (also callable as `g8.api.call("assign_lists_to_folder_lists_folders_assignments_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+File up to 500 lists into one folder, or out of every folder. FREE.
+
+All or nothing: if ANY list is not visible to the key the whole call is a
+404 and nothing moves, so a caller cannot learn which ids exist by which
+ones were filed. `folder_id` null unfiles them.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ListFolderBulkAssignRequest` | yes | Request body; fields below. |
+
+Body fields (`ListFolderBulkAssignRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.audience_ids` | `Array<integer>` | yes | The lists to move, 1 to 500. min items 1, max items 500 |
+| `body.folder_id` | `string (uuid) \| null` | no | The folder. Null takes the list OUT of every folder. |
+
+**Returns**: no JSON body is declared for the success response.
+
+**Example**
+
+```ts
+const result = await g8.api.lists.assignListsToFolder({ body: { audience_ids: [123] } });
+```
+
+---
+
+<a id="op-checklistintegrity"></a>
+
+### `g8.api.lists.checkListIntegrity(input)`
+
+**Check List Integrity**
+
+- HTTP: `POST /api/v1/lists/{list_id}/integrity-check`
+- operationId: `check_list_integrity_lists__list_id__integrity_check_post` (also callable as `g8.api.call("check_list_integrity_lists__list_id__integrity_check_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `lists:read`
+
+How complete the list's data is: per field, how many contacts have a usable value.
+
+Covers the default contact fields (email, phone, name, company, ...) plus any
+`extra_fields` named. Reads only; nothing is written or enriched.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.list_id` | `integer` | yes | List (audience) id. |
+| `body` | `IntegrityCheckRequest` | no | Request body; fields below. |
+
+Body fields (`IntegrityCheckRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.extra_fields` | `Array<string> \| null` | no | Enrichment / AI / dynamic columns to measure on top of the default fields - the `column_name_db` values from `GET /lists/{list_id}/data-columns`. |
+
+**Returns** `ApiResponse_SequencerPayload_`: the envelope `{ data: SequencerPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.lists.checkListIntegrity({ path: { list_id: 1 } });
+```
+
+---
+
+<a id="op-createemptylist"></a>
+
+### `g8.api.lists.createEmptyList(input)`
+
+**Create Empty List**
+
+- HTTP: `POST /api/v1/lists/create-empty`
+- operationId: `create_empty_list_lists_create_empty_post` (also callable as `g8.api.call("create_empty_list_lists_create_empty_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Create a list with nothing in it, to fill later.
+
+SEND AN `idempotency_key`. Without one a retried request makes a second
+empty list, and a duplicate list is harder to notice than a failed call.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CreateEmptyListRequest` | yes | Request body; fields below. |
+
+Body fields (`CreateEmptyListRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.source` | `"csv" \| "graph8" \| "FormSubmission" \| "visitor" \| "salesforce" \| "hubspot" \| "keyword" \| "intent" \| …` | yes | Where the list comes from, e.g. `csv`. |
+| `body.title` | `string` | yes | min length 1, max length 200 |
+| `body.description` | `string \| null` | no |  |
+| `body.idempotency_key` | `string \| null` | no | Retry-safe: the same key returns the same list. |
+| `body.is_dynamic` | `boolean` | no | A dynamic list re-runs its query; a static one keeps what it is given. default `false` |
+| `body.request_fingerprint` | `string \| null` | no |  |
+| `body.status` | `"completed" \| "processing" \| "failed"` | no | default `"completed"` |
+| `body.type` | `"contacts" \| "companies" \| "suppressions" \| "deals" \| "leads"` | no | What the list holds. The wire name is `type`; the app's field is `type_` because `type` is a Python builtin, and the alias keeps the wire name identical to the app's. default `"contacts"` |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.lists.createEmptyList({ body: { source: "csv", title: "Example" } });
+```
+
+---
+
+<a id="op-createlist"></a>
+
+### `g8.api.lists.createList(input)`
+
+**Create List**
+
+- HTTP: `POST /api/v1/lists`
+- operationId: `create_list_lists_post` (also callable as `g8.api.call("create_list_lists_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+- ★ Hand-written: [`g8.lists.create()`](../sdk-clients.md#g8-lists-create)
+
+Create a new empty list.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ListCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`ListCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.title` | `string` | yes | Name of the list |
+| `body.description` | `string \| null` | no | Optional note describing the list's purpose, readable by agents (#16641) max length 2000 |
+| `body.type` | `string` | no | List type: contacts, companies, suppressions, deals, leads default `"contacts"` |
+
+**Returns** `ApiResponse_ListCreateResponse_`: the envelope `{ data: ListCreateResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ListCreateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `integer` | yes |  |
+| `title` | `string` | yes |  |
+| `description` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `total` | `integer` | no | default `0` |
+| `type` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.lists.createList({ body: { title: "Example" } });
+```
+
+---
+
+<a id="op-createlistfolder"></a>
+
+### `g8.api.lists.createListFolder(input)`
+
+**Create List Folder**
+
+- HTTP: `POST /api/v1/lists/folders`
+- operationId: `create_list_folder_lists_folders_post` (also callable as `g8.api.call("create_list_folder_lists_folders_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Create a folder. Titles are de-duplicated per owner by the same
+internal path the app uses, so a repeat title returns its 409 unchanged.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ListFolderCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`ListFolderCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.title` | `string` | yes | Folder title. min length 1, max length 120 |
+| `body.visibility` | `"private" \| "org" \| null` | no | Defaults to `private` when omitted. |
+
+**Returns** `ApiResponse_ListFolderResponse_`: the envelope `{ data: ListFolderResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ListFolderResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_by` | `string` | yes | User id that created the folder. |
+| `id` | `string (uuid)` | yes | Folder id. |
+| `is_owner` | `boolean` | yes | True when the calling key's org owns the folder. |
+| `list_count` | `integer` | yes | Number of lists currently filed in this folder. |
+| `title` | `string` | yes | Display title. |
+| `visibility` | `string` | yes | `private` (owner only) or `org` (browse-only for teammates). |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.lists.createListFolder({ body: { title: "Example" } });
+```
+
+---
+
+<a id="op-createmasterlist"></a>
+
+### `g8.api.lists.createMasterList(input)`
+
+**Create Master List**
+
+- HTTP: `POST /api/v1/lists/masters`
+- operationId: `create_master_list_lists_masters_post` (also callable as `g8.api.call("create_master_list_lists_masters_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Create a master list from other lists.
+
+`include_all_sources` takes EVERY list of this type, including ones
+created later - a standing rule rather than a snapshot, and it makes
+`source_list_ids` irrelevant.
+
+The first sync runs in the BACKGROUND, so the list comes back empty and
+fills shortly after.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CreateMasterListRequest` | yes | Request body; fields below. |
+
+Body fields (`CreateMasterListRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.title` | `string` | yes | max length 500 |
+| `body.include_all_sources` | `boolean` | no | Take EVERY list of this type instead of the named ones, including ones created later. `source_list_ids` is then ignored. default `false` |
+| `body.source_list_ids` | `Array<integer>` | no | The lists to union. |
+| `body.type` | `"contacts" \| "companies" \| "suppressions" \| "deals" \| "leads"` | no | Wire name is `type`; see `CreateEmptyListRequest`. default `"contacts"` |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.lists.createMasterList({ body: { title: "Example" } });
+```
+
+---
+
+<a id="op-deletecompaniesfromlist"></a>
+
+### `g8.api.lists.deleteCompaniesFromList(input)`
+
+**Delete Companies From List**
+
+- HTTP: `DELETE /api/v1/lists/{audience_id}/companies`
+- operationId: `delete_companies_from_list_lists__audience_id__companies_delete` (also callable as `g8.api.call("delete_companies_from_list_lists__audience_id__companies_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `lists:delete`
+
+Remove companies from a list.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | List (audience) id. |
+| `body` | `DeleteCompaniesFromListRequest` | yes | Request body; fields below. |
+| `query.agFilterModel` | `string \| null` | no | AgGrid filter JSON. Every company in the list matching it is removed, IN ADDITION to `company_ids` - the two combine rather than the filter narrowing the ids. |
+
+Body fields (`DeleteCompaniesFromListRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.company_ids` | `Array<integer>` | no |  |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `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.lists.deleteCompaniesFromList({ path: { audience_id: 123 }, body: {} });
+```
+
+---
+
+<a id="op-deleteleadsfromlist"></a>
+
+### `g8.api.lists.deleteLeadsFromList(input)`
+
+**Delete Leads From List**
+
+- HTTP: `DELETE /api/v1/lists/{audience_id}/leads`
+- operationId: `delete_leads_from_list_lists__audience_id__leads_delete` (also callable as `g8.api.call("delete_leads_from_list_lists__audience_id__leads_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `lists:delete`
+
+Remove leads from a list.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | List (audience) id. |
+| `body` | `DeleteLeadsFromListRequest` | yes | Request body; fields below. |
+
+Body fields (`DeleteLeadsFromListRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.lead_ids` | `Array<integer>` | yes | The leads to remove. |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `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.lists.deleteLeadsFromList({ path: { audience_id: 123 }, body: { lead_ids: [123] } });
+```
+
+---
+
+<a id="op-deletelist"></a>
+
+### `g8.api.lists.deleteList(input)`
+
+**Delete List**
+
+- HTTP: `DELETE /api/v1/lists/{list_id}`
+- operationId: `delete_list_lists__list_id__delete` (also callable as `g8.api.call("delete_list_lists__list_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `lists:delete`
+- ★ Hand-written: [`g8.lists.delete()`](../sdk-clients.md#g8-lists-delete)
+
+Soft-delete a list.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.list_id` | `integer` | yes | List ID |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `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.lists.deleteList({ path: { list_id: 123 } });
+```
+
+---
+
+<a id="op-deletelistfolder"></a>
+
+### `g8.api.lists.deleteListFolder(input)`
+
+**Delete List Folder**
+
+- HTTP: `DELETE /api/v1/lists/folders/{folder_id}`
+- operationId: `delete_list_folder_lists_folders__folder_id__delete` (also callable as `g8.api.call("delete_list_folder_lists_folders__folder_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `lists:delete`
+
+Delete a folder. The lists inside it are NOT deleted - they are
+unfiled, exactly as in the app.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.folder_id` | `string (uuid)` | yes | Folder id. |
+
+**Returns**: no JSON body is declared for the success response.
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.lists.deleteListFolder({ path: { folder_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-deletesuppressionsfromlist"></a>
+
+### `g8.api.lists.deleteSuppressionsFromList(input)`
+
+**Delete Suppressions From List**
+
+- HTTP: `DELETE /api/v1/lists/{audience_id}/suppressions`
+- operationId: `delete_suppressions_from_list_lists__audience_id__suppressions_delete` (also callable as `g8.api.call("delete_suppressions_from_list_lists__audience_id__suppressions_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `lists:delete`
+
+Remove suppressions from a suppression list.
+
+Removing a suppression makes those people CONTACTABLE again - this is the
+one removal here that changes who can be emailed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | List (audience) id. |
+| `body` | `DeleteSuppressionsFromListRequest` | yes | Request body; fields below. |
+
+Body fields (`DeleteSuppressionsFromListRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.suppression_ids` | `Array<integer>` | yes | The suppressions to remove. |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `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.lists.deleteSuppressionsFromList({ path: { audience_id: 123 }, body: { suppression_ids: [123] } });
+```
+
+---
+
+<a id="op-downloadlist"></a>
+
+### `g8.api.lists.downloadList(input)`
+
+**Download List**
+
+- HTTP: `GET /api/v1/lists/{audience_id}/download`
+- operationId: `download_list_lists__audience_id__download_get` (also callable as `g8.api.call("download_list_lists__audience_id__download_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `lists:read`
+
+Every row of a list as a CSV or XLSX file. FREE.
+
+Unbounded: the file holds the WHOLE list. CSV comes back as text; XLSX as
+base64 in `content` with `encoding: "base64"`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes |  |
+| `query.format` | `"csv" \| "xlsx"` | no | `csv` or `xlsx`. default `"xlsx"` |
+| `query.columns` | `Array<string> \| null` | no | Only these columns. Omit for every column. LinkedIn profile URLs are always kept, as in the app. |
+
+**Returns** `ApiResponse_ListDownloadPayload_`: the envelope `{ data: ListDownloadPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ListDownloadPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `content` | `string` | yes |  |
+| `encoding` | `"utf-8" \| "base64"` | yes |  |
+| `filename` | `string` | yes |  |
+| `format` | `"csv" \| "xlsx"` | yes |  |
+| `media_type` | `string` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.lists.downloadList({ path: { audience_id: 123 } });
+```
+
+---
+
+<a id="op-generatetrackedlinks"></a>
+
+### `g8.api.lists.generateTrackedLinks(input)`
+
+**Generate Tracked Links**
+
+- HTTP: `POST /api/v1/lists/{audience_id}/generate-tracked-links`
+- operationId: `generate_tracked_links_lists__audience_id__generate_tracked_links_post` (also callable as `g8.api.call("generate_tracked_links_lists__audience_id__generate_tracked_links_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Mint one tracked URL per row, into a column on the list.
+
+`params_template` interpolates this list's own columns - check
+`GET /tracked-links/columns` first, because an unresolvable name produces
+a link with an empty parameter rather than an error.
+
+`placement` only applies when `shorten` is off.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | List (audience) id. |
+| `body` | `GenerateTrackedLinksRequest` | yes | Request body; fields below. |
+
+Body fields (`GenerateTrackedLinksRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.destination_url` | `string` | yes | Absolute http(s) URL every link points at. |
+| `body.link_name` | `string` | yes | What this set of links is called. |
+| `body.column_title` | `string \| null` | no | Column to write the links into. |
+| `body.params_template` | `Record<string, string>` | no | Query parameters to interpolate per row, e.g. {'utm_term': '{company}'}. |
+| `body.placement` | `"fragment" \| "query"` | no | Where the token goes on a NON-shortened URL: `fragment` (#t=…) or `query` (?g8t=…). Ignored when `shorten` is on. default `"fragment"` |
+| `body.shorten` | `boolean` | no | Use the short-link domain. default `false` |
+| `body.stream_id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.lists.generateTrackedLinks({
+  path: { audience_id: 123 },
+  body: { destination_url: "https://example.com", link_name: "Example" },
+});
+```
+
+---
+
+<a id="op-getlistcolumncapabilities"></a>
+
+### `g8.api.lists.getListColumnCapabilities(input)`
+
+**Get List Column Capabilities**
+
+- HTTP: `GET /api/v1/lists/{audience_id}/column-capabilities`
+- operationId: `get_list_column_capabilities_lists__audience_id__column_capabilities_get` (also callable as `g8.api.call("get_list_column_capabilities_lists__audience_id__column_capabilities_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `lists:read`
+
+Which dynamic columns this list can carry, and what may be written.
+
+Read this before `PATCH /dynamic-value`: a column that is not writable
+here is refused there, and the capability map is the only way to know
+which is which without guessing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | List (audience) id. |
+| `query.object_type` | `"mashup_contacts" \| "mashup_companies"` | yes | Which grid's columns: contacts or companies. |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.lists.getListColumnCapabilities({
+  path: { audience_id: 123 },
+  query: { object_type: "mashup_contacts" },
+});
+```
+
+---
+
+<a id="op-getlistcontacts"></a>
+
+### `g8.api.lists.getListContacts(input)`
+
+**Get List Contacts**
+
+- HTTP: `GET /api/v1/lists/{list_id}/contacts`
+- operationId: `get_list_contacts_lists__list_id__contacts_get` (also callable as `g8.api.call("get_list_contacts_lists__list_id__contacts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `lists:read`
+- ★ Hand-written: [`g8.lists.contacts()`](../sdk-clients.md#g8-lists-contacts)
+
+Get contacts in a specific list.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.list_id` | `integer` | yes | List ID |
+| `query.page` | `integer` | no | Page number (1-indexed) default `1` |
+| `query.limit` | `integer` | no | Items per page (max 200) default `50` |
+
+**Returns** `ApiResponse_list_ContactListItem__`: the envelope `{ data: Array<ContactListItem>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ContactListItem` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `city` | `string \| null` | no |  |
+| `company_id` | `integer \| null` | no |  |
+| `country` | `string \| null` | no |  |
+| `custom_fields` | `Record<string, string \| null> \| null` | no |  |
+| `direct_phone` | `string \| null` | no |  |
+| `first_name` | `string \| null` | no |  |
+| `id` | `integer \| null` | no |  |
+| `job_department` | `string \| null` | no |  |
+| `job_title` | `string \| null` | no |  |
+| `last_name` | `string \| null` | no |  |
+| `linkedin_url` | `string \| null` | no |  |
+| `mobile_phone` | `string \| null` | no |  |
+| `owner_id` | `string \| null` | no |  |
+| `owner_name` | `string \| null` | no |  |
+| `seniority_level` | `string \| null` | no |  |
+| `state` | `string \| null` | no |  |
+| `work_email` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.lists.getListContacts({ path: { list_id: 123 } });
+```
+
+---
+
+<a id="op-getlistkeywordlinks"></a>
+
+### `g8.api.lists.getListKeywordLinks(input)`
+
+**Get List Keyword Links**
+
+- HTTP: `GET /api/v1/lists/{audience_id}/keyword-links`
+- operationId: `get_list_keyword_links_lists__audience_id__keyword_links_get` (also callable as `g8.api.call("get_list_keyword_links_lists__audience_id__keyword_links_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `lists:read`
+
+Which intent keywords auto-populate this list.
+
+The authoritative source: the link lives in
+`cb_keyword_sync_configs.list_id`, not in the list's own query, so a list
+can be fed by a keyword while its `icp_query` says nothing about it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | List (audience) id. |
+
+**Returns** `ApiResponse_ListCollectionPayload_`: the envelope `{ data: ListCollectionPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ListCollectionPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.lists.getListKeywordLinks({ path: { audience_id: 123 } });
+```
+
+---
+
+<a id="op-getlistperformance"></a>
+
+### `g8.api.lists.getListPerformance(input?)`
+
+**Get List Performance**
+
+- HTTP: `GET /api/v1/lists/performance`
+- operationId: `get_list_performance_lists_performance_get` (also callable as `g8.api.call("get_list_performance_lists_performance_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `lists:read`
+
+Engagement counters for one list or every list the key may see.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.list_id` | `integer \| null` | no | Filter to a single list. Omit for all lists. |
+| `query.days` | `integer \| null` | no | Restrict sends/events to the last N days. Omit for all-time. Ignored when start_date and end_date are both supplied. |
+| `query.start_date` | `string \| null` | no | Inclusive start of an anchored range, `YYYY-MM-DD`. Requires end_date. |
+| `query.end_date` | `string \| null` | no | Inclusive end of an anchored range, `YYYY-MM-DD`. |
+
+**Returns** `ApiResponse_ListPerformanceResponse_`: the envelope `{ data: ListPerformanceResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ListPerformanceResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<ListPerformanceItem>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.lists.getListPerformance();
+```
+
+---
+
+<a id="op-gettrackedlinkcolumns"></a>
+
+### `g8.api.lists.getTrackedLinkColumns(input)`
+
+**Get Tracked Link Columns**
+
+- HTTP: `GET /api/v1/lists/{audience_id}/tracked-links/columns`
+- operationId: `get_tracked_link_columns_lists__audience_id__tracked_links_columns_get` (also callable as `g8.api.call("get_tracked_link_columns_lists__audience_id__tracked_links_columns_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `lists:read`
+
+Which of this list's columns can be interpolated into a tracked link.
+
+The source of the names usable in `params_template` - anything else
+resolves to nothing and produces a link with an empty parameter.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | List (audience) id. |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.lists.getTrackedLinkColumns({ path: { audience_id: 123 } });
+```
+
+---
+
+<a id="op-listdatacolumns"></a>
+
+### `g8.api.lists.listDataColumns(input)`
+
+**List Data Columns**
+
+- HTTP: `GET /api/v1/lists/{list_id}/data-columns`
+- operationId: `list_data_columns_lists__list_id__data_columns_get` (also callable as `g8.api.call("list_data_columns_lists__list_id__data_columns_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `lists:read`
+
+The enrichment (waterfall), AI and dynamic columns this list carries.
+
+Pass a row's `column_name_db` in `extra_fields` on `POST .../integrity-check`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.list_id` | `integer` | yes | List (audience) id. |
+
+**Returns** `ApiResponse_SequencerListPayload_`: the envelope `{ data: SequencerListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SequencerListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.lists.listDataColumns({ path: { list_id: 1 } });
+```
+
+---
+
+<a id="op-listlistfolders"></a>
+
+### `g8.api.lists.listListFolders(input?)`
+
+**List List Folders**
+
+- HTTP: `GET /api/v1/lists/folders`
+- operationId: `list_list_folders_lists_folders_get` (also callable as `g8.api.call("list_list_folders_lists_folders_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `lists:read`
+
+Folders the key's org owns, plus org-visible folders owned by teammates.
+
+`assignments` maps list id -> folder id, which is what a rebuilt Lists
+screen needs to place each list without a second round trip.
+
+The internal `list_folders` takes TWO different scope classes: a
+campaign_builder `service_scope` (carrying `.is_scoped`/`.allowed_list_ids`)
+and an audiences `visibility_scope`. They are resolved by distinct
+dependencies - passing one object as both raises AttributeError -> 500.
+
+**Input**: none.
+
+**Returns** `ApiResponse_ListFolderIndexResponse_`: the envelope `{ data: ListFolderIndexResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ListFolderIndexResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `assignments` | `Record<string, string (uuid)>` | no | Map of list id -> folder id for every filed list. |
+| `folders` | `Array<ListFolderResponse>` | no |  |
+| `shared_folders` | `Array<ListFolderResponse>` | no |  |
+| `starred_ids` | `Array<integer>` | no | List ids the caller has starred. |
+
+**Example**
+
+```ts
+const result = await g8.api.lists.listListFolders();
+```
+
+---
+
+<a id="op-listlists"></a>
+
+### `g8.api.lists.listLists(input?)`
+
+**List Lists**
+
+- HTTP: `GET /api/v1/lists`
+- operationId: `list_lists_lists_get` (also callable as `g8.api.call("list_lists_lists_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `lists:read`
+- ★ Hand-written: [`g8.lists.list()`](../sdk-clients.md#g8-lists-list)
+
+List all lists (audiences) in the organization.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.page` | `integer` | no | Page number (1-indexed) default `1` |
+| `query.limit` | `integer` | no | Items per page (max 200) default `50` |
+
+**Returns** `ApiResponse_list_ListResponse__`: the envelope `{ data: Array<ListResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `integer` | yes |  |
+| `title` | `string` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `description` | `string \| null` | no | Agent/human-readable note describing the list's purpose (#16641) |
+| `is_dynamic` | `boolean` | no | default `false` |
+| `source` | `string \| null` | no | Source of the list |
+| `status` | `string \| null` | no |  |
+| `tags` | `Array<string>` | no |  |
+| `total` | `integer` | no | default `0` |
+| `type` | `string \| null` | no | List type (contacts, companies, suppressions, deals, leads) |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.lists.listLists();
+```
+
+---
+
+<a id="op-listmasterlists"></a>
+
+### `g8.api.lists.listMasterLists(input?)`
+
+**List Master Lists**
+
+- HTTP: `GET /api/v1/lists/masters`
+- operationId: `list_master_lists_lists_masters_get` (also callable as `g8.api.call("list_master_lists_lists_masters_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `lists:read`
+
+Master lists: the ones that union other lists and stay in sync.
+
+**Input**: none.
+
+**Returns** `ApiResponse_ListCollectionPayload_`: the envelope `{ data: ListCollectionPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ListCollectionPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.lists.listMasterLists();
+```
+
+---
+
+<a id="op-patchdynamicvalue"></a>
+
+### `g8.api.lists.patchDynamicValue(input)`
+
+**Patch Dynamic Value**
+
+- HTTP: `PATCH /api/v1/lists/{audience_id}/dynamic-value`
+- operationId: `patch_dynamic_value_lists__audience_id__dynamic_value_patch` (also callable as `g8.api.call("patch_dynamic_value_lists__audience_id__dynamic_value_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Write ONE cell of a user-owned dynamic column.
+
+Fail-closed: a protected, unknown, other-list or other-org destination is
+refused rather than written somewhere plausible.
+
+Send `expected_value` to make the write conditional on the cell not having
+moved. Omit it and the write wins unconditionally, which on a shared grid
+means overwriting a colleague's edit without knowing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | List (audience) id. |
+| `body` | `PatchDynamicValueRequest` | yes | Request body; fields below. |
+
+Body fields (`PatchDynamicValueRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.column_key` | `string` | yes | Dynamic column key, e.g. `udo_notes`. |
+| `body.object_type` | `"mashup_contacts" \| "mashup_companies"` | yes |  |
+| `body.record_id` | `integer` | yes | Grid row id. |
+| `body.expected_value` | `unknown \| null` | no | Refuse the write unless the cell still holds this. Omit to force. |
+| `body.value` | `unknown \| null` | no | New value. Null CLEARS the cell. |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.lists.patchDynamicValue({
+  path: { audience_id: 123 },
+  body: {
+    column_key: "example",
+    object_type: "mashup_contacts",
+    record_id: 123,
+  },
+});
+```
+
+---
+
+<a id="op-previewlistownertransfer"></a>
+
+### `g8.api.lists.previewListOwnerTransfer(input)`
+
+**Preview List Owner Transfer**
+
+- HTTP: `GET /api/v1/lists/{audience_id}/owner/preview`
+- operationId: `preview_list_owner_transfer_lists__audience_id__owner_preview_get` (also callable as `g8.api.call("preview_list_owner_transfer_lists__audience_id__owner_preview_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `lists:read`
+
+What a transfer WOULD do, before doing it. Changes nothing.
+
+Worth calling first: `list_and_records` re-owns every record in the list,
+which can change who else can see them, and this says how many before you
+commit.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | List (audience) id. |
+| `query.new_owner_user_id` | `string` | yes | Candidate owner's PropelAuth user id. |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.lists.previewListOwnerTransfer({ path: { audience_id: 123 }, query: { new_owner_user_id: "id" } });
+```
+
+---
+
+<a id="op-reassignlistowner"></a>
+
+### `g8.api.lists.reassignListOwner(input)`
+
+**Reassign List Owner**
+
+- HTTP: `PATCH /api/v1/lists/{audience_id}/owner`
+- operationId: `reassign_list_owner_lists__audience_id__owner_patch` (also callable as `g8.api.call("reassign_list_owner_lists__audience_id__owner_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Hand a list to someone else.
+
+`mode="list_and_records"` ALSO re-owns every record in the list. Under
+record-level scoping that changes who can see them, so preview it first.
+
+This route carries no `verify_list_access_dep` in the app - the transfer
+rules are enforced inside the handler instead, and they are stricter than
+the per-list read gate rather than weaker.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | List (audience) id. |
+| `body` | `ReassignListOwnerRequest` | yes | Request body; fields below. |
+
+Body fields (`ReassignListOwnerRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.owner_email` | `string (email)` | yes | Must agree with the user id - the app verifies both. Typed as an email at the request layer because the app's model is `EmailStr` and is built inside the handler: a malformed address would otherwise raise there and escape as a 500 rather than a 422. |
+| `body.owner_user_id` | `string` | yes | min length 1, max length 255 |
+| `body.mode` | `"list_only" \| "list_and_records"` | no | `list_only` moves just the list. `list_and_records` also re-owns every record in it, which can change who else can see them. default `"list_only"` |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.lists.reassignListOwner({
+  path: { audience_id: 123 },
+  body: { owner_email: "jane@acme.com", owner_user_id: "id" },
+});
+```
+
+---
+
+<a id="op-recordlistopened"></a>
+
+### `g8.api.lists.recordListOpened(input)`
+
+**Record List Opened**
+
+- HTTP: `POST /api/v1/lists/folders/activity/{audience_id}`
+- operationId: `record_list_opened_lists_folders_activity__audience_id__post` (also callable as `g8.api.call("record_list_opened_lists_folders_activity__audience_id__post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Record that this key opened a list, for the "recent" shelf. FREE.
+
+Recents come back in `GET /lists/folders` as `recent_items`, most recent
+first. A list the key cannot see is a 404.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | The list (audience) id. |
+
+**Returns**: no JSON body is declared for the success response.
+
+**Example**
+
+```ts
+const result = await g8.api.lists.recordListOpened({ path: { audience_id: 123 } });
+```
+
+---
+
+<a id="op-refreshdynamiclist"></a>
+
+### `g8.api.lists.refreshDynamicList(input)`
+
+**Refresh Dynamic List**
+
+- HTTP: `POST /api/v1/lists/{audience_id}/refresh`
+- operationId: `refresh_dynamic_list_lists__audience_id__refresh_post` (also callable as `g8.api.call("refresh_dynamic_list_lists__audience_id__refresh_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Re-run a dynamic list's query now.
+
+Membership can go DOWN as well as up: a record that no longer matches
+leaves. Only meaningful for a list created with `is_dynamic`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | List (audience) id. |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.lists.refreshDynamicList({ path: { audience_id: 123 } });
+```
+
+---
+
+<a id="op-refreshmasterlistnow"></a>
+
+### `g8.api.lists.refreshMasterListNow(input)`
+
+**Refresh Master List Now**
+
+- HTTP: `POST /api/v1/lists/{audience_id}/master-refresh`
+- operationId: `refresh_master_list_now_lists__audience_id__master_refresh_post` (also callable as `g8.api.call("refresh_master_list_now_lists__audience_id__master_refresh_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Re-sync a master list from its sources now. Returns add/remove counts.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | List (audience) id. |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.lists.refreshMasterListNow({ path: { audience_id: 123 } });
+```
+
+---
+
+<a id="op-removecontactsfromlist"></a>
+
+### `g8.api.lists.removeContactsFromList(input)`
+
+**Remove Contacts From List**
+
+- HTTP: `DELETE /api/v1/lists/{list_id}/contacts`
+- operationId: `remove_contacts_from_list_lists__list_id__contacts_delete` (also callable as `g8.api.call("remove_contacts_from_list_lists__list_id__contacts_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `lists:delete`
+- ★ Hand-written: [`g8.lists.removeContacts()`](../sdk-clients.md#g8-lists-removecontacts)
+
+Remove contacts from a list.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.list_id` | `integer` | yes | List ID |
+| `body` | `RemoveContactsFromListRequest` | yes | Request body; fields below. |
+
+Body fields (`RemoveContactsFromListRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.contact_ids` | `Array<integer>` | yes | List of contact IDs to remove |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `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.lists.removeContactsFromList({ path: { list_id: 123 }, body: { contact_ids: [123] } });
+```
+
+---
+
+<a id="op-starlist"></a>
+
+### `g8.api.lists.starList(input)`
+
+**Star List**
+
+- HTTP: `PUT /api/v1/lists/folders/stars/{audience_id}`
+- operationId: `star_list_lists_folders_stars__audience_id__put` (also callable as `g8.api.call("star_list_lists_folders_stars__audience_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Star or unstar a list for this key. FREE.
+
+Starred ids come back in `GET /lists/folders` as `starred_ids`. A list the
+key cannot see is a 404.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | The list (audience) id. |
+| `body` | `ListStarRequest` | yes | Request body; fields below. |
+
+Body fields (`ListStarRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.starred` | `boolean` | yes | True to star, false to unstar. |
+
+**Returns**: no JSON body is declared for the success response.
+
+**Example**
+
+```ts
+const result = await g8.api.lists.starList({ path: { audience_id: 123 }, body: { starred: true } });
+```
+
+---
+
+<a id="op-updatelist"></a>
+
+### `g8.api.lists.updateList(input)`
+
+**Update List**
+
+- HTTP: `PATCH /api/v1/lists/{list_id}`
+- operationId: `update_list_lists__list_id__patch` (also callable as `g8.api.call("update_list_lists__list_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Update a list's name and/or its agent-readable description (#16641).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.list_id` | `integer` | yes | List ID |
+| `body` | `ListUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`ListUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.title` | `string` | yes | New name for the list min length 1 |
+| `body.description` | `string \| null` | no | New purpose note for the list (#16641). Omit to leave the current description unchanged; send an empty string to clear it. max length 2000 |
+
+**Returns** `ApiResponse_ListResponse_`: the envelope `{ data: ListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `integer` | yes |  |
+| `title` | `string` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `description` | `string \| null` | no | Agent/human-readable note describing the list's purpose (#16641) |
+| `is_dynamic` | `boolean` | no | default `false` |
+| `source` | `string \| null` | no | Source of the list |
+| `status` | `string \| null` | no |  |
+| `tags` | `Array<string>` | no |  |
+| `total` | `integer` | no | default `0` |
+| `type` | `string \| null` | no | List type (contacts, companies, suppressions, deals, leads) |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.lists.updateList({ path: { list_id: 123 }, body: { title: "Example" } });
+```
+
+---
+
+<a id="op-updatelistfolder"></a>
+
+### `g8.api.lists.updateListFolder(input)`
+
+**Update List Folder**
+
+- HTTP: `PATCH /api/v1/lists/folders/{folder_id}`
+- operationId: `update_list_folder_lists_folders__folder_id__patch` (also callable as `g8.api.call("update_list_folder_lists_folders__folder_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Rename a folder or change its visibility. Omitted fields are untouched.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.folder_id` | `string (uuid)` | yes | Folder id. |
+| `body` | `ListFolderUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`ListFolderUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.title` | `string \| null` | no | min length 1, max length 120 |
+| `body.visibility` | `"private" \| "org" \| null` | no |  |
+
+**Returns** `ApiResponse_ListFolderResponse_`: the envelope `{ data: ListFolderResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ListFolderResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_by` | `string` | yes | User id that created the folder. |
+| `id` | `string (uuid)` | yes | Folder id. |
+| `is_owner` | `boolean` | yes | True when the calling key's org owns the folder. |
+| `list_count` | `integer` | yes | Number of lists currently filed in this folder. |
+| `title` | `string` | yes | Display title. |
+| `visibility` | `string` | yes | `private` (owner only) or `org` (browse-only for teammates). |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.lists.updateListFolder({
+  path: { folder_id: "00000000-0000-0000-0000-000000000000" },
+  body: {},
+});
+```
+
+---
+
+<a id="op-updatemasterlistconfig"></a>
+
+### `g8.api.lists.updateMasterListConfig(input)`
+
+**Update Master List Config**
+
+- HTTP: `PATCH /api/v1/lists/{audience_id}/master-config`
+- operationId: `update_master_list_config_lists__audience_id__master_config_patch` (also callable as `g8.api.call("update_master_list_config_lists__audience_id__master_config_patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Replace a master list's sources.
+
+A REPLACE, not a merge: a source you omit stops feeding the list. The
+config is saved synchronously and the re-sync runs afterwards, so a 200
+means the config is stored, not that membership has caught up.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.audience_id` | `integer` | yes | List (audience) id. |
+| `body` | `UpdateMasterListConfigRequest` | yes | Request body; fields below. |
+
+Body fields (`UpdateMasterListConfigRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.include_all_sources` | `boolean` | no | default `false` |
+| `body.source_list_ids` | `Array<integer>` | no |  |
+
+**Returns** `ApiResponse_ListPayload_`: the envelope `{ data: ListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.lists.updateMasterListConfig({ path: { audience_id: 123 }, body: {} });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-listperformanceitem"></a>
+
+### `ListPerformanceItem`
+
+Per-list engagement counters. Fields mirror the app's own item.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `list_id` | `integer \| null` | no |  |
+| `title` | `string \| null` | no |  |