@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/notes.md

@@ -0,0 +1,888 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.notes`: Notes
+
+19 operations (6 read, 9 write, 4 destructive).
+
+8 of these also have a hand-written method (`g8.notes`), 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: [notes.d.ts](notes.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`createCompanyNote`](#op-createcompanynote) ★ | `POST /api/v1/companies/{company_id}/notes` | write | `notes:write` | Create Company Note |
+| [`createDealNote`](#op-createdealnote) ★ | `POST /api/v1/deals/{deal_id}/notes` | write | `notes:write` | Create Deal Note |
+| [`createNote`](#op-createnote) ★ | `POST /api/v1/contacts/{contact_id}/notes` | write | `notes:write` | Create Note |
+| [`createNoteReply`](#op-createnotereply) | `POST /api/v1/notes/{note_id}/replies` | write | `notes:write` | Create Note Reply |
+| [`createRecordNote`](#op-createrecordnote) | `POST /api/v1/notes` | write | `notes:write` | Create Record Note |
+| [`deleteNote`](#op-deletenote) ★ | `DELETE /api/v1/notes/{note_id}` | destructive | `notes:delete` | Delete Note |
+| [`deleteNoteReply`](#op-deletenotereply) | `DELETE /api/v1/notes/replies/{reply_id}` | destructive | `notes:delete` | Delete Note Reply |
+| [`linkNoteRecord`](#op-linknoterecord) | `POST /api/v1/notes/{note_id}/records` | write | `notes:write` | Link Note Record |
+| [`listCompanyNotes`](#op-listcompanynotes) ★ | `GET /api/v1/companies/{company_id}/notes` | read | `notes:read` | List Company Notes |
+| [`listDealNotes`](#op-listdealnotes) ★ | `GET /api/v1/deals/{deal_id}/notes` | read | `notes:read` | List Deal Notes |
+| [`listNoteReplies`](#op-listnotereplies) | `GET /api/v1/notes/{note_id}/replies` | read | `notes:read` | List Note Replies |
+| [`listNotes`](#op-listnotes) ★ | `GET /api/v1/contacts/{contact_id}/notes` | read | `notes:read` | List Notes |
+| [`listNotesForContacts`](#op-listnotesforcontacts) | `POST /api/v1/notes/batch` | read | `notes:read` | List Notes For Contacts |
+| [`listNotesForRecord`](#op-listnotesforrecord) | `GET /api/v1/notes` | read | `notes:read` | List Notes For Record |
+| [`reopenNoteThread`](#op-reopennotethread) | `DELETE /api/v1/notes/{note_id}/resolve` | destructive | `notes:delete` | Reopen Note Thread |
+| [`resolveNoteThread`](#op-resolvenotethread) | `POST /api/v1/notes/{note_id}/resolve` | write | `notes:write` | Resolve Note Thread |
+| [`unlinkNoteRecord`](#op-unlinknoterecord) | `DELETE /api/v1/notes/{note_id}/records` | destructive | `notes:delete` | Unlink Note Record |
+| [`updateNote`](#op-updatenote) ★ | `PATCH /api/v1/notes/{note_id}` | write | `notes:write` | Update Note |
+| [`updateNoteReply`](#op-updatenotereply) | `PUT /api/v1/notes/replies/{reply_id}` | write | `notes:write` | Update Note Reply |
+
+---
+
+<a id="op-createcompanynote"></a>
+
+### `g8.api.notes.createCompanyNote(input)`
+
+**Create Company Note**
+
+- HTTP: `POST /api/v1/companies/{company_id}/notes`
+- operationId: `create_company_note_companies__company_id__notes_post` (also callable as `g8.api.call("create_company_note_companies__company_id__notes_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `notes:write`
+- ★ Hand-written: [`g8.notes.createForCompany()`](../sdk-clients.md#g8-notes-createforcompany)
+
+Create a note on a company.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | Company ID (mashup_companies.id) |
+| `body` | `NoteCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`NoteCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.content` | `string` | yes | Note content (plain text or markdown) |
+
+**Returns** `ApiResponse_NoteResponse_`: the envelope `{ data: NoteResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`NoteResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `content` | `string` | yes |  |
+| `entity_id` | `string` | yes |  |
+| `entity_type` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `created_at` | `string \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `created_by_name` | `string \| null` | no |  |
+| `read_only` | `boolean` | no | default `false` |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.notes.createCompanyNote({ path: { company_id: 123 }, body: { content: "example" } });
+```
+
+---
+
+<a id="op-createdealnote"></a>
+
+### `g8.api.notes.createDealNote(input)`
+
+**Create Deal Note**
+
+- HTTP: `POST /api/v1/deals/{deal_id}/notes`
+- operationId: `create_deal_note_deals__deal_id__notes_post` (also callable as `g8.api.call("create_deal_note_deals__deal_id__notes_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `notes:write`
+- ★ Hand-written: [`g8.notes.createForDeal()`](../sdk-clients.md#g8-notes-createfordeal)
+
+Create a note on a deal.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal ID (UUID) |
+| `body` | `NoteCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`NoteCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.content` | `string` | yes | Note content (plain text or markdown) |
+
+**Returns** `ApiResponse_NoteResponse_`: the envelope `{ data: NoteResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`NoteResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `content` | `string` | yes |  |
+| `entity_id` | `string` | yes |  |
+| `entity_type` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `created_at` | `string \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `created_by_name` | `string \| null` | no |  |
+| `read_only` | `boolean` | no | default `false` |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.notes.createDealNote({ path: { deal_id: "id" }, body: { content: "example" } });
+```
+
+---
+
+<a id="op-createnote"></a>
+
+### `g8.api.notes.createNote(input)`
+
+**Create Note**
+
+- HTTP: `POST /api/v1/contacts/{contact_id}/notes`
+- operationId: `create_note_contacts__contact_id__notes_post` (also callable as `g8.api.call("create_note_contacts__contact_id__notes_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `notes:write`
+- ★ Hand-written: [`g8.notes.create()`](../sdk-clients.md#g8-notes-create)
+
+Create a note on a contact.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact ID |
+| `body` | `NoteCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`NoteCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.content` | `string` | yes | Note content (plain text or markdown) |
+
+**Returns** `ApiResponse_NoteResponse_`: the envelope `{ data: NoteResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`NoteResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `content` | `string` | yes |  |
+| `entity_id` | `string` | yes |  |
+| `entity_type` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `created_at` | `string \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `created_by_name` | `string \| null` | no |  |
+| `read_only` | `boolean` | no | default `false` |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.notes.createNote({ path: { contact_id: 123 }, body: { content: "example" } });
+```
+
+---
+
+<a id="op-createnotereply"></a>
+
+### `g8.api.notes.createNoteReply(input)`
+
+**Create Note Reply**
+
+- HTTP: `POST /api/v1/notes/{note_id}/replies`
+- operationId: `create_note_reply_notes__note_id__replies_post` (also callable as `g8.api.call("create_note_reply_notes__note_id__replies_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `notes:write`
+
+Post a reply on this note's thread. INTERNAL to your organisation.
+
+Nothing here reaches the contact the note is about. `mentioned_user_ids`
+notifies those people inside graph8.
+
+Write access is checked against the RECORD the note hangs off, not the
+note: replying is a write to that record's collaboration surface.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.note_id` | `string` | yes | Note id (UUID). |
+| `body` | `NoteReplyCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`NoteReplyCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.body` | `string` | yes | Reply text. |
+| `body.author_avatar_url` | `string \| null` | no | Avatar to show beside the reply. |
+| `body.mentioned_user_ids` | `Array<string>` | no | Users to notify. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.notes.createNoteReply({ path: { note_id: "id" }, body: { body: "example" } });
+```
+
+---
+
+<a id="op-createrecordnote"></a>
+
+### `g8.api.notes.createRecordNote(input)`
+
+**Create Record Note**
+
+- HTTP: `POST /api/v1/notes`
+- operationId: `create_record_note_notes_post` (also callable as `g8.api.call("create_record_note_notes_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `notes:write`
+
+Create a note attached to one or MORE records.
+
+With `records`, the first entry is the primary record and every entry is
+linked; without it, `entity_type`/`entity_id` name the single record.
+Every record is authorised for write before anything is stored.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `RecordNoteCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`RecordNoteCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.content` | `string` | yes | Note body. |
+| `body.entity_id` | `string` | no | Id of that record. default `""` |
+| `body.entity_type` | `string` | no | Record type the note is attached to. default `""` |
+| `body.mentioned_users` | `Array<NoteMentionedUser>` | no | Teammates mentioned in the note. |
+| `body.records` | `Array<Record<string, unknown>> \| null` | no | Further records to attach, each `{entity_type, entity_id}`. |
+| `body.source_url` | `string \| null` | no | Where the note was taken. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.notes.createRecordNote({ body: { content: "example" } });
+```
+
+---
+
+<a id="op-deletenote"></a>
+
+### `g8.api.notes.deleteNote(input)`
+
+**Delete Note**
+
+- HTTP: `DELETE /api/v1/notes/{note_id}`
+- operationId: `delete_note_notes__note_id__delete` (also callable as `g8.api.call("delete_note_notes__note_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `notes:delete`
+- ★ Hand-written: [`g8.notes.delete()`](../sdk-clients.md#g8-notes-delete)
+
+Delete a note. Works on a contact, company or deal note.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.note_id` | `string` | yes | Note 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.notes.deleteNote({ path: { note_id: "id" } });
+```
+
+---
+
+<a id="op-deletenotereply"></a>
+
+### `g8.api.notes.deleteNoteReply(input)`
+
+**Delete Note Reply**
+
+- HTTP: `DELETE /api/v1/notes/replies/{reply_id}`
+- operationId: `delete_note_reply_notes_replies__reply_id__delete` (also callable as `g8.api.call("delete_note_reply_notes_replies__reply_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `notes:delete`
+
+Delete a reply. AUTHOR ONLY. The rest of the thread stays.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.reply_id` | `string` | yes | Reply id (UUID). |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `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.notes.deleteNoteReply({ path: { reply_id: "id" } });
+```
+
+---
+
+<a id="op-linknoterecord"></a>
+
+### `g8.api.notes.linkNoteRecord(input)`
+
+**Link Note Record**
+
+- HTTP: `POST /api/v1/notes/{note_id}/records`
+- operationId: `link_note_record_notes__note_id__records_post` (also callable as `g8.api.call("link_note_record_notes__note_id__records_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `notes:write`
+
+Also file this note under another record. Idempotent.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.note_id` | `string` | yes | Note id (UUID). |
+| `body` | `NoteRecordLinkRequest` | yes | Request body; fields below. |
+
+Body fields (`NoteRecordLinkRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.entity_id` | `string` | yes | Record id. |
+| `body.entity_type` | `string` | yes | Record type. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.notes.linkNoteRecord({
+  path: { note_id: "id" },
+  body: { entity_id: "id", entity_type: "example" },
+});
+```
+
+---
+
+<a id="op-listcompanynotes"></a>
+
+### `g8.api.notes.listCompanyNotes(input)`
+
+**List Company Notes**
+
+- HTTP: `GET /api/v1/companies/{company_id}/notes`
+- operationId: `list_company_notes_companies__company_id__notes_get` (also callable as `g8.api.call("list_company_notes_companies__company_id__notes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `notes:read`
+- ★ Hand-written: [`g8.notes.listForCompany()`](../sdk-clients.md#g8-notes-listforcompany)
+
+List all notes on a company.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | Company ID (mashup_companies.id) |
+
+**Returns** `ApiResponse_list_NoteResponse__`: the envelope `{ data: Array<NoteResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`NoteResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `content` | `string` | yes |  |
+| `entity_id` | `string` | yes |  |
+| `entity_type` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `created_at` | `string \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `created_by_name` | `string \| null` | no |  |
+| `read_only` | `boolean` | no | default `false` |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.notes.listCompanyNotes({ path: { company_id: 123 } });
+```
+
+---
+
+<a id="op-listdealnotes"></a>
+
+### `g8.api.notes.listDealNotes(input)`
+
+**List Deal Notes**
+
+- HTTP: `GET /api/v1/deals/{deal_id}/notes`
+- operationId: `list_deal_notes_deals__deal_id__notes_get` (also callable as `g8.api.call("list_deal_notes_deals__deal_id__notes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `notes:read`
+- ★ Hand-written: [`g8.notes.listForDeal()`](../sdk-clients.md#g8-notes-listfordeal)
+
+List all notes on a deal.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.deal_id` | `string` | yes | Deal ID (UUID) |
+
+**Returns** `ApiResponse_list_NoteResponse__`: the envelope `{ data: Array<NoteResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`NoteResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `content` | `string` | yes |  |
+| `entity_id` | `string` | yes |  |
+| `entity_type` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `created_at` | `string \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `created_by_name` | `string \| null` | no |  |
+| `read_only` | `boolean` | no | default `false` |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.notes.listDealNotes({ path: { deal_id: "id" } });
+```
+
+---
+
+<a id="op-listnotereplies"></a>
+
+### `g8.api.notes.listNoteReplies(input)`
+
+**List Note Replies**
+
+- HTTP: `GET /api/v1/notes/{note_id}/replies`
+- operationId: `list_note_replies_notes__note_id__replies_get` (also callable as `g8.api.call("list_note_replies_notes__note_id__replies_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `notes:read`
+
+The thread under a note, plus its resolution row if it has one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.note_id` | `string` | yes | Note id (UUID). |
+
+**Returns** `ApiResponse_CrmCollectionPayload_`: the envelope `{ data: CrmCollectionPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CrmCollectionPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.notes.listNoteReplies({ path: { note_id: "id" } });
+```
+
+---
+
+<a id="op-listnotes"></a>
+
+### `g8.api.notes.listNotes(input)`
+
+**List Notes**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/notes`
+- operationId: `list_notes_contacts__contact_id__notes_get` (also callable as `g8.api.call("list_notes_contacts__contact_id__notes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `notes:read`
+- ★ Hand-written: [`g8.notes.list()`](../sdk-clients.md#g8-notes-list)
+
+List all notes on a contact.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact ID |
+
+**Returns** `ApiResponse_list_NoteResponse__`: the envelope `{ data: Array<NoteResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`NoteResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `content` | `string` | yes |  |
+| `entity_id` | `string` | yes |  |
+| `entity_type` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `created_at` | `string \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `created_by_name` | `string \| null` | no |  |
+| `read_only` | `boolean` | no | default `false` |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.notes.listNotes({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-listnotesforcontacts"></a>
+
+### `g8.api.notes.listNotesForContacts(input)`
+
+**List Notes For Contacts**
+
+- HTTP: `POST /api/v1/notes/batch`
+- operationId: `list_notes_for_contacts_notes_batch_post` (also callable as `g8.api.call("list_notes_for_contacts_notes_batch_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `notes:read`
+
+The notes of many contacts in one read, grouped by contact. Writes nothing.
+
+POST only because the id list is a body. Every contact is authorised first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `NoteBatchRequest` | yes | Request body; fields below. |
+
+Body fields (`NoteBatchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.contact_ids` | `Array<string>` | yes | Contacts whose notes to read in one call. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.notes.listNotesForContacts({ body: { contact_ids: ["id"] } });
+```
+
+---
+
+<a id="op-listnotesforrecord"></a>
+
+### `g8.api.notes.listNotesForRecord(input)`
+
+**List Notes For Record**
+
+- HTTP: `GET /api/v1/notes`
+- operationId: `list_notes_for_record_notes_get` (also callable as `g8.api.call("list_notes_for_record_notes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `notes:read`
+
+Every note on one record, including notes that only MENTION it.
+
+The per-record reads (`GET /contacts/{id}/notes` and friends) return the
+notes attached to the record; this one also follows secondary links, so a
+note filed on a deal that names this contact appears here too.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.entity_type` | `string` | yes | Record type, e.g. `contact`, `company`, `deal`. |
+| `query.entity_id` | `string` | yes | Id of that record. |
+
+**Returns** `ApiResponse_CrmCollectionPayload_`: the envelope `{ data: CrmCollectionPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CrmCollectionPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.notes.listNotesForRecord({ query: { entity_type: "example", entity_id: "id" } });
+```
+
+---
+
+<a id="op-reopennotethread"></a>
+
+### `g8.api.notes.reopenNoteThread(input)`
+
+**Reopen Note Thread**
+
+- HTTP: `DELETE /api/v1/notes/{note_id}/resolve`
+- operationId: `reopen_note_thread_notes__note_id__resolve_delete` (also callable as `g8.api.call("reopen_note_thread_notes__note_id__resolve_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `notes:delete`
+
+Reopen this note's discussion. Nothing is deleted.
+
+Spelled as a DELETE because what it removes is the RESOLUTION, not the
+thread - the app's own spelling, and the inverse of the POST above. It is
+a WRITE on the underlying record despite the verb, and the gate says so
+explicitly rather than inferring it from the method.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.note_id` | `string` | yes | Note id (UUID). |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `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.notes.reopenNoteThread({ path: { note_id: "id" } });
+```
+
+---
+
+<a id="op-resolvenotethread"></a>
+
+### `g8.api.notes.resolveNoteThread(input)`
+
+**Resolve Note Thread**
+
+- HTTP: `POST /api/v1/notes/{note_id}/resolve`
+- operationId: `resolve_note_thread_notes__note_id__resolve_post` (also callable as `g8.api.call("resolve_note_thread_notes__note_id__resolve_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `notes:write`
+
+Mark this note's discussion resolved.
+
+Idempotent - re-resolving returns the existing row rather than creating a
+second one. The replies are untouched.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.note_id` | `string` | yes | Note id (UUID). |
+| `body` | `ResolveThreadRequest` | no | Request body; fields below. |
+
+Body fields (`ResolveThreadRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.resolution_note` | `string \| null` | no | Why it was resolved. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.notes.resolveNoteThread({ path: { note_id: "id" } });
+```
+
+---
+
+<a id="op-unlinknoterecord"></a>
+
+### `g8.api.notes.unlinkNoteRecord(input)`
+
+**Unlink Note Record**
+
+- HTTP: `DELETE /api/v1/notes/{note_id}/records`
+- operationId: `unlink_note_record_notes__note_id__records_delete` (also callable as `g8.api.call("unlink_note_record_notes__note_id__records_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `notes:delete`
+
+Stop filing this note under a record. The note itself is kept.
+
+The app takes the record in a DELETE body; it is a query string here,
+because a body on DELETE is dropped by many HTTP clients and proxies.
+The app refuses to remove a note's LAST record, so a note never orphans.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.note_id` | `string` | yes | Note id (UUID). |
+| `query.entity_type` | `string` | yes | Record type to unlink. |
+| `query.entity_id` | `string` | yes | Record id to unlink. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `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.notes.unlinkNoteRecord({
+  path: { note_id: "id" },
+  query: { entity_type: "example", entity_id: "id" },
+});
+```
+
+---
+
+<a id="op-updatenote"></a>
+
+### `g8.api.notes.updateNote(input)`
+
+**Update Note**
+
+- HTTP: `PATCH /api/v1/notes/{note_id}`
+- operationId: `update_note_notes__note_id__patch` (also callable as `g8.api.call("update_note_notes__note_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `notes:write`
+- ★ Hand-written: [`g8.notes.update()`](../sdk-clients.md#g8-notes-update)
+
+Update a note's content. Works on a contact, company or deal note.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.note_id` | `string` | yes | Note ID |
+| `body` | `NoteUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`NoteUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.content` | `string` | yes | Updated note content |
+
+**Returns** `ApiResponse_NoteResponse_`: the envelope `{ data: NoteResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`NoteResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `content` | `string` | yes |  |
+| `entity_id` | `string` | yes |  |
+| `entity_type` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `created_at` | `string \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `created_by_name` | `string \| null` | no |  |
+| `read_only` | `boolean` | no | default `false` |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.notes.updateNote({ path: { note_id: "id" }, body: { content: "example" } });
+```
+
+---
+
+<a id="op-updatenotereply"></a>
+
+### `g8.api.notes.updateNoteReply(input)`
+
+**Update Note Reply**
+
+- HTTP: `PUT /api/v1/notes/replies/{reply_id}`
+- operationId: `update_note_reply_notes_replies__reply_id__put` (also callable as `g8.api.call("update_note_reply_notes_replies__reply_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `notes:write`
+
+Edit a reply. AUTHOR ONLY.
+
+An organisation key has no member identity, so it is not the author of
+anything a human wrote - it can edit the replies it posted itself.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.reply_id` | `string` | yes | Reply id (UUID). |
+| `body` | `NoteReplyUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`NoteReplyUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.body` | `string` | yes | Replacement text. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.notes.updateNoteReply({ path: { reply_id: "id" }, body: { body: "example" } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-notementioneduser"></a>
+
+### `NoteMentionedUser`
+
+Mirrors `contacts.usecases.notes.cmd.MentionedUser`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes | User id. |
+| `name` | `string` | yes | Display name. |
+| `email` | `string \| null` | no | Email address. |