@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/agents.md

@@ -0,0 +1,2860 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.agents`: Agents
+
+65 operations (33 read, 22 write, 3 destructive, 7 billable).
+
+No hand-written client covers this area. Call it through `g8.api.agents.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [agents.d.ts](agents.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`answerAgentDiscovery`](#op-answeragentdiscovery) | `POST /api/v1/agent/onboarding/discovery/answer` | write | `workflows:write` | Answer Agent Discovery |
+| [`cancelAgentWorkItem`](#op-cancelagentworkitem) | `POST /api/v1/agent/work-items/{work_item_id}/cancel` | destructive | `workflows:delete` | Cancel Agent Work Item |
+| [`captureAgentEntryPoint`](#op-captureagententrypoint) | `POST /api/v1/agent/onboarding/entry-point` | write | `workflows:write` | Capture Agent Entry Point |
+| [`captureAgentSignupAttribution`](#op-captureagentsignupattribution) | `POST /api/v1/agent/onboarding/attribution` | write | `workflows:write` | Capture Agent Signup Attribution |
+| [`confirmAgentSessionCard`](#op-confirmagentsessioncard) | `POST /api/v1/agent/sessions/{session_id}/cards/{card_id}/confirm` | write | `workflows:write` | Confirm Agent Session Card |
+| [`createAgentSession`](#op-createagentsession) | `POST /api/v1/agent/sessions` | write | `workflows:write` | Create Agent Session |
+| [`createAgentVoiceDraft`](#op-createagentvoicedraft) | `POST /api/v1/agent/sessions/voice/draft` | write | `workflows:write` | Create Agent Voice Draft |
+| [`createAgentWorkItem`](#op-createagentworkitem) | `POST /api/v1/agent/work-items` | billable | `workflows:run` | Create Agent Work Item |
+| [`decideAgentOperatorApproval`](#op-decideagentoperatorapproval) | `POST /api/v1/agent/operators/{operator}/approvals/{task_id}/decide` | billable | `workflows:run` | Decide Agent Operator Approval |
+| [`deleteAgentSession`](#op-deleteagentsession) | `DELETE /api/v1/agent/sessions/{session_id}` | destructive | `workflows:delete` | Delete Agent Session |
+| [`endAgentSessionVoice`](#op-endagentsessionvoice) | `DELETE /api/v1/agent/sessions/{session_id}/voice/{voice_id}` | destructive | `workflows:delete` | End Agent Session Voice |
+| [`getAgentDiscovery`](#op-getagentdiscovery) | `GET /api/v1/agent/onboarding/discovery` | read | `workflows:read` | Get Agent Discovery |
+| [`getAgentDiscoveryCampaignBrief`](#op-getagentdiscoverycampaignbrief) | `GET /api/v1/agent/onboarding/discovery/campaign-brief` | read | `workflows:read` | Get Agent Discovery Campaign Brief |
+| [`getAgentDiscoveryReport`](#op-getagentdiscoveryreport) | `GET /api/v1/agent/onboarding/discovery/report` | read | `workflows:read` | Get Agent Discovery Report |
+| [`getAgentMemory`](#op-getagentmemory) | `GET /api/v1/agent/memory` | read | `workflows:read` | Get Agent Memory |
+| [`getAgentOperatingModel`](#op-getagentoperatingmodel) | `GET /api/v1/agent/operators/operating-model` | read | `workflows:read` | Get Agent Operating Model |
+| [`getAgentOperatorCatalog`](#op-getagentoperatorcatalog) | `GET /api/v1/agent/operators/{operator}/catalog` | read | `workflows:read` | Get Agent Operator Catalog |
+| [`getAgentOperatorFeedbackSummary`](#op-getagentoperatorfeedbacksummary) | `GET /api/v1/agent/operators/{operator}/feedback/summary` | read | `workflows:read` | Get Agent Operator Feedback Summary |
+| [`getAgentOperatorForApprovalTask`](#op-getagentoperatorforapprovaltask) | `GET /api/v1/agent/operators/approvals/{task_id}/operator` | read | `workflows:read` | Get Agent Operator For Approval Task |
+| [`getAgentOperatorHealth`](#op-getagentoperatorhealth) | `GET /api/v1/agent/operators/{operator}/health` | read | `workflows:read` | Get Agent Operator Health |
+| [`getAgentOperatorRecipient`](#op-getagentoperatorrecipient) | `GET /api/v1/agent/operators/{operator}/recipient` | read | `workflows:read` | Get Agent Operator Recipient |
+| [`getAgentOperatorScorecard`](#op-getagentoperatorscorecard) | `GET /api/v1/agent/operators/{operator}/scorecard` | read | `workflows:read` | Get Agent Operator Scorecard |
+| [`getAgentOperatorStatus`](#op-getagentoperatorstatus) | `GET /api/v1/agent/operators/{operator}/status` | read | `workflows:read` | Get Agent Operator Status |
+| [`getAgentOperatorsSummary`](#op-getagentoperatorssummary) | `GET /api/v1/agent/operators/summary` | read | `workflows:read` | Get Agent Operators Summary |
+| [`getAgentOversight`](#op-getagentoversight) | `GET /api/v1/agent/oversight` | read | `workflows:read` | Get Agent Oversight |
+| [`getAgentProactiveOpener`](#op-getagentproactiveopener) | `GET /api/v1/agent/proactive-opener` | read | `workflows:read` | Get Agent Proactive Opener |
+| [`getAgentPushbackEvidence`](#op-getagentpushbackevidence) | `GET /api/v1/agent/evidence/pushback` | read | `workflows:read` | Get Agent Pushback Evidence |
+| [`getAgentSession`](#op-getagentsession) | `GET /api/v1/agent/sessions/{session_id}` | read | `workflows:read` | Get Agent Session |
+| [`getAgentSessionState`](#op-getagentsessionstate) | `GET /api/v1/agent/sessions/{session_id}/state` | read | `workflows:read` | Get Agent Session State |
+| [`getAgentSessionVoiceCapability`](#op-getagentsessionvoicecapability) | `GET /api/v1/agent/sessions/{session_id}/voice` | read | `workflows:read` | Get Agent Session Voice Capability |
+| [`getAgentVoiceCapability`](#op-getagentvoicecapability) | `GET /api/v1/agent/sessions/voice/capability` | read | `workflows:read` | Get Agent Voice Capability |
+| [`listAgentOperatorActions`](#op-listagentoperatoractions) | `GET /api/v1/agent/operators/{operator}/actions` | read | `workflows:read` | List Agent Operator Actions |
+| [`listAgentOperatorActivity`](#op-listagentoperatoractivity) | `GET /api/v1/agent/operators/{operator}/activity` | read | `workflows:read` | List Agent Operator Activity |
+| [`listAgentOperatorActivityRecords`](#op-listagentoperatoractivityrecords) | `GET /api/v1/agent/operators/{operator}/activity/{task_id}/records` | read | `workflows:read` | List Agent Operator Activity Records |
+| [`listAgentOperatorApprovalSources`](#op-listagentoperatorapprovalsources) | `GET /api/v1/agent/operators/approvals/sources` | read | `workflows:read` | List Agent Operator Approval Sources |
+| [`listAgentOperatorCollections`](#op-listagentoperatorcollections) | `GET /api/v1/agent/operators/{operator}/collections` | read | `workflows:read` | List Agent Operator Collections |
+| [`listAgentOperatorFindings`](#op-listagentoperatorfindings) | `GET /api/v1/agent/operators/{operator}/findings` | read | `workflows:read` | List Agent Operator Findings |
+| [`listAgentOperatorSkills`](#op-listagentoperatorskills) | `GET /api/v1/agent/operators/{operator}/skills` | read | `workflows:read` | List Agent Operator Skills |
+| [`listAgentOperators`](#op-listagentoperators) | `GET /api/v1/agent/operators` | read | `workflows:read` | List Agent Operators |
+| [`listAgentSessions`](#op-listagentsessions) | `GET /api/v1/agent/sessions` | read | `workflows:read` | List Agent Sessions |
+| [`listAgentSpecialists`](#op-listagentspecialists) | `GET /api/v1/agent/specialists` | read | `workflows:read` | List Agent Specialists |
+| [`listAgentWorkItems`](#op-listagentworkitems) | `GET /api/v1/agent/work-items` | read | `workflows:read` | List Agent Work Items |
+| [`loadCopilotIntentContext`](#op-loadcopilotintentcontext) | `POST /api/v1/copilot/context/load` | write | `workflows:write` | Load Copilot Intent Context |
+| [`markAgentSessionRead`](#op-markagentsessionread) | `PUT /api/v1/agent/sessions/{session_id}/read` | write | `workflows:write` | Mark Agent Session Read |
+| [`openAgentDiscovery`](#op-openagentdiscovery) | `POST /api/v1/agent/onboarding/discovery/open` | write | `workflows:write` | Open Agent Discovery |
+| [`pinAgentSession`](#op-pinagentsession) | `POST /api/v1/agent/sessions/{session_id}/pin` | write | `workflows:write` | Pin Agent Session |
+| [`postAgentChat`](#op-postagentchat) | `POST /api/v1/agent/chat` | billable | `workflows:run` | Post Agent Chat |
+| [`postAgentOnboardingCatchup`](#op-postagentonboardingcatchup) | `POST /api/v1/agent/onboarding/catchup` | write | `workflows:write` | Post Agent Onboarding Catchup |
+| [`postAgentSessionMessage`](#op-postagentsessionmessage) | `POST /api/v1/agent/sessions/{session_id}/messages` | write | `workflows:write` | Post Agent Session Message |
+| [`projectAgentDiscovery`](#op-projectagentdiscovery) | `POST /api/v1/agent/onboarding/discovery/project` | write | `workflows:write` | Project Agent Discovery |
+| [`putAgentOperatingModel`](#op-putagentoperatingmodel) | `PUT /api/v1/agent/operators/operating-model` | write | `workflows:write` | Put Agent Operating Model |
+| [`quoteAgentSessionVoice`](#op-quoteagentsessionvoice) | `POST /api/v1/agent/sessions/{session_id}/voice/quote` | read | `workflows:read` | Quote Agent Session Voice |
+| [`ratifyAgentDiscovery`](#op-ratifyagentdiscovery) | `POST /api/v1/agent/onboarding/discovery/ratify` | write | `workflows:write` | Ratify Agent Discovery |
+| [`renameAgentSession`](#op-renameagentsession) | `POST /api/v1/agent/sessions/{session_id}/rename` | write | `workflows:write` | Rename Agent Session |
+| [`requestAgentApprovalChanges`](#op-requestagentapprovalchanges) | `POST /api/v1/agent/approvals/{approval_id}/request-changes` | write | `workflows:write` | Request Agent Approval Changes |
+| [`searchAgentMentions`](#op-searchagentmentions) | `POST /api/v1/agent/mention-search` | read | `workflows:read` | Search Agent Mentions |
+| [`setAgentOperatorEnabled`](#op-setagentoperatorenabled) | `PUT /api/v1/agent/operators/{operator}/enabled` | billable | `workflows:run` | Set Agent Operator Enabled |
+| [`setAgentOperatorRecipient`](#op-setagentoperatorrecipient) | `PUT /api/v1/agent/operators/{operator}/recipient` | write | `workflows:write` | Set Agent Operator Recipient |
+| [`setAgentOperatorTrustDial`](#op-setagentoperatortrustdial) | `PUT /api/v1/agent/operators/{operator}/skills/{skill_key}` | billable | `workflows:run` | Set Agent Operator Trust Dial |
+| [`setupAgentDiscoverySignals`](#op-setupagentdiscoverysignals) | `POST /api/v1/agent/onboarding/discovery/signals` | write | `workflows:write` | Setup Agent Discovery Signals |
+| [`startAgentSessionVoice`](#op-startagentsessionvoice) | `POST /api/v1/agent/sessions/{session_id}/voice` | billable | `workflows:run` | Start Agent Session Voice |
+| [`steerAgentWorkItem`](#op-steeragentworkitem) | `POST /api/v1/agent/work-items/{work_item_id}/steer` | write | `workflows:write` | Steer Agent Work Item |
+| [`submitAgentDomainResponse`](#op-submitagentdomainresponse) | `POST /api/v1/agent/onboarding/domain-response` | write | `workflows:write` | Submit Agent Domain Response |
+| [`takeAgentDiscoveryTurn`](#op-takeagentdiscoveryturn) | `POST /api/v1/agent/onboarding/discovery/turn` | billable | `workflows:run` | Take Agent Discovery Turn |
+| [`updateAgentSession`](#op-updateagentsession) | `PATCH /api/v1/agent/sessions/{session_id}` | write | `workflows:write` | Update Agent Session |
+
+---
+
+<a id="op-answeragentdiscovery"></a>
+
+### `g8.api.agents.answerAgentDiscovery(input)`
+
+**Answer Agent Discovery**
+
+- HTTP: `POST /api/v1/agent/onboarding/discovery/answer`
+- operationId: `answer_agent_discovery_agent_onboarding_discovery_answer_post` (also callable as `g8.api.call("answer_agent_discovery_agent_onboarding_discovery_answer_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Record ONE graded answer.
+
+`grade` is not decoration. A `red` grade stores NO VALUE and burns a rung of
+the probe ladder - the agent asks again a different way rather than keeping
+a guess. Storing an unusable answer as data is how a confident, wrong ICP
+gets built.
+
+`field_key` must be a real framework field; anything else is refused by the
+handler by name rather than being written as a stray key.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DiscoveryAnswerRequest` | yes | Request body; fields below. |
+
+Body fields (`DiscoveryAnswerRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.field_key` | `string` | yes | Which discovery field this answers. |
+| `body.grade` | `string` | yes | Confidence in the answer: `green` (certain), `amber` (a working assumption) or `red` (a guess). Amber and red answers come back in `coverage.amber_fields` so they can be revisited. |
+| `body.move_number` | `integer \| null` | no | Interview move this answers. |
+| `body.session_id` | `string \| null` | no | Canvas session to report into. |
+| `body.source` | `string` | no | Who supplied it. Defaults to `user`. default `"user"` |
+| `body.value` | `unknown` | no | The answer. Shape depends on the field. |
+
+**Returns** `ApiResponse_OnboardingPayload_`: the envelope `{ data: OnboardingPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.answerAgentDiscovery({ body: { field_key: "example", grade: "example" } });
+```
+
+---
+
+<a id="op-cancelagentworkitem"></a>
+
+### `g8.api.agents.cancelAgentWorkItem(input)`
+
+**Cancel Agent Work Item**
+
+- HTTP: `POST /api/v1/agent/work-items/{work_item_id}/cancel`
+- operationId: `cancel_agent_work_item_agent_work_items__work_item_id__cancel_post` (also callable as `g8.api.call("cancel_agent_work_item_agent_work_items__work_item_id__cancel_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `workflows:delete`
+
+Stop a work item.
+
+Stops the LOOP. Anything the agent already did - a sequence launched, a
+record written - stays done; cancelling is not an undo.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.work_item_id` | `string` | yes | Work item id (UUID). |
+
+**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.agents.cancelAgentWorkItem({ path: { work_item_id: "id" } });
+```
+
+---
+
+<a id="op-captureagententrypoint"></a>
+
+### `g8.api.agents.captureAgentEntryPoint(input)`
+
+**Capture Agent Entry Point**
+
+- HTTP: `POST /api/v1/agent/onboarding/entry-point`
+- operationId: `capture_agent_entry_point_agent_onboarding_entry_point_post` (also callable as `g8.api.call("capture_agent_entry_point_agent_onboarding_entry_point_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Record which product the customer signed up for. FIRST WRITER WINS.
+
+The entry point maps 1:1 to a plan template, so it chooses what the agent
+proposes doing first. It is a one-shot ATTRIBUTION, not a settable
+preference: if the org already has one, this call changes nothing and
+reports the existing value.
+
+Read `captured` rather than the status code - a 200 with `captured: false`
+means someone else got there first, which is a normal outcome and not an
+error.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `EntryPointCaptureRequest` | yes | Request body; fields below. |
+
+Body fields (`EntryPointCaptureRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.entry_point` | `"dialer" \| "sequencer" \| "marketplace" \| "dev" \| "calendar" \| "email_inbox" \| "full"` | yes | The signup entry point. Maps 1:1 to a plan template, so this chooses what the agent will propose doing first. FIRST WRITER WINS: if the org already has one captured, this call reports the existing value and changes nothing. |
+
+**Returns** `ApiResponse_OnboardingPayload_`: the envelope `{ data: OnboardingPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.captureAgentEntryPoint({ body: { entry_point: "dialer" } });
+```
+
+---
+
+<a id="op-captureagentsignupattribution"></a>
+
+### `g8.api.agents.captureAgentSignupAttribution(input)`
+
+**Capture Agent Signup Attribution**
+
+- HTTP: `POST /api/v1/agent/onboarding/attribution`
+- operationId: `capture_agent_signup_attribution_agent_onboarding_attribution_post` (also callable as `g8.api.call("capture_agent_signup_attribution_agent_onboarding_attribution_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Record first-touch attribution - UTM tags, ad click ids, landing page.
+
+FIRST WRITER WINS on every key, so this is safe to call once per session
+and safe to retry. Nothing already captured is overwritten.
+
+Every field is optional, which means an empty body is legal and does
+nothing. The response reports each destination separately
+(`organization_persisted`, `contact_persisted`, ...) because attribution
+lands in more than one place and a partial write is worth knowing about -
+`complete` is the single field that says all of them took.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SignupAttributionRequest` | yes | Request body; fields below. |
+
+Body fields (`SignupAttributionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.entry_point` | `string \| null` | no | Signup entry-point slug. max length 50 |
+| `body.fbclid` | `string \| null` | no | max length 255 |
+| `body.gbraid` | `string \| null` | no | max length 255 |
+| `body.gclid` | `string \| null` | no | max length 255 |
+| `body.landing_at` | `string (date-time) \| null` | no |  |
+| `body.landing_page_url` | `string \| null` | no | max length 2048 |
+| `body.signup_referrer` | `string \| null` | no | max length 2048 |
+| `body.utm_campaign` | `string \| null` | no | max length 255 |
+| `body.utm_content` | `string \| null` | no | max length 255 |
+| `body.utm_id` | `string \| null` | no | max length 255 |
+| `body.utm_medium` | `string \| null` | no | max length 255 |
+| `body.utm_source` | `string \| null` | no | max length 255 |
+| `body.utm_term` | `string \| null` | no | max length 255 |
+| `body.wbraid` | `string \| null` | no | max length 255 |
+
+**Returns** `ApiResponse_OnboardingPayload_`: the envelope `{ data: OnboardingPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.captureAgentSignupAttribution({ body: {} });
+```
+
+---
+
+<a id="op-confirmagentsessioncard"></a>
+
+### `g8.api.agents.confirmAgentSessionCard(input)`
+
+**Confirm Agent Session Card**
+
+- HTTP: `POST /api/v1/agent/sessions/{session_id}/cards/{card_id}/confirm`
+- operationId: `confirm_agent_session_card_agent_sessions__session_id__cards__card_id__confirm_post` (also callable as `g8.api.call("confirm_agent_session_card_agent_sessions__session_id__cards__card_id__confirm_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Answer a confirm card the agent posted into a session.
+
+Onboarding runs stop on these ("is this your company?", "are these your
+competitors?") and resume when the answer lands, usually within ten
+seconds. Idempotent for the same `state`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.session_id` | `string` | yes | Session id (UUID). |
+| `path.card_id` | `string` | yes | The card's id in the session. |
+| `body` | `AgentCardConfirmationRequest` | yes | Request body; fields below. |
+
+Body fields (`AgentCardConfirmationRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.state` | `"approved" \| "edited" \| "rejected"` | yes | `approved` accepts the card as proposed, `edited` accepts it with your `edits`, `rejected` sends it back. Re-sending the same state is a no-op; a different state overwrites. |
+| `body.edits` | `Record<string, unknown> \| null` | no | Per-field overrides for an `edited` card. The shape is the card's own and varies by card kind. |
+| `body.note` | `string \| null` | no | Why, in your words. max length 2000 |
+
+**Returns** `ApiResponse_AgentConversationPayload_`: the envelope `{ data: AgentConversationPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.confirmAgentSessionCard({
+  path: { session_id: "id", card_id: "id" },
+  body: { state: "approved" },
+});
+```
+
+---
+
+<a id="op-createagentsession"></a>
+
+### `g8.api.agents.createAgentSession(input)`
+
+**Create Agent Session**
+
+- HTTP: `POST /api/v1/agent/sessions`
+- operationId: `create_agent_session_agent_sessions_post` (also callable as `g8.api.call("create_agent_session_agent_sessions_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Open a session, optionally seeded with messages.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `AgentSessionCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`AgentSessionCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.messages` | `Array<Record<string, unknown>> \| null` | no | Optional seed messages to open the session with. |
+| `body.mode` | `string` | no | Session mode. default `"general"` |
+| `body.title` | `string \| null` | no | Optional title; the app derives one when omitted. |
+
+**Returns** `ApiResponse_AgentSession_`: the envelope `{ data: AgentSession, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentSession` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_at` | `string (date-time) \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `is_pinned` | `boolean \| null` | no |  |
+| `mode` | `string \| null` | no | Session mode, e.g. `general`. |
+| `title` | `string \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.createAgentSession({ body: {} });
+```
+
+---
+
+<a id="op-createagentvoicedraft"></a>
+
+### `g8.api.agents.createAgentVoiceDraft(input)`
+
+**Create Agent Voice Draft**
+
+- HTTP: `POST /api/v1/agent/sessions/voice/draft`
+- operationId: `create_agent_voice_draft_agent_sessions_voice_draft_post` (also callable as `g8.api.call("create_agent_voice_draft_agent_sessions_voice_draft_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Create an EMPTY session to speak into.
+
+It creates only the conversation - never a synthetic opening turn from the
+agent. That is deliberate in the app and worth preserving: a fabricated
+first message would appear in the transcript as something the agent said
+when it had not yet heard anything.
+
+`session_id` is caller-generated, so a client can open its socket and
+create the row without a round trip between the two. Sending the same id
+twice does not create a second session.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `VoiceDraftRequest` | yes | Request body; fields below. |
+
+Body fields (`VoiceDraftRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.session_id` | `string (uuid)` | yes | The id the new session will have - CALLER-GENERATED, not server-assigned. That is what lets a client open the socket and create the row without a round trip between them. Reusing an id does not create a second session. |
+
+**Returns** `ApiResponse_AgentSessionStatePayload_`: the envelope `{ data: AgentSessionStatePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.createAgentVoiceDraft({ body: { session_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-createagentworkitem"></a>
+
+### `g8.api.agents.createAgentWorkItem(input)`
+
+**Create Agent Work Item**
+
+- HTTP: `POST /api/v1/agent/work-items`
+- operationId: `create_agent_work_item_agent_work_items_post` (also callable as `g8.api.call("create_agent_work_item_agent_work_items_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `workflows:run`
+
+Start a unit of autonomous work. THE AGENT BEGINS PLANNING IMMEDIATELY.
+
+`agent_id` selects the planner template. A known id gets its own template;
+anything else falls back to `full`, which is why it is an open string
+rather than an enum - an enum would reject the ad-hoc case the planner
+explicitly supports.
+
+`visibility` defaults to `private`: work started through a key is not
+visible org-wide unless asked for.
+
+`user_email` defaults to the identity the key was minted under, so the item
+belongs to a real person rather than to nobody.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `AgentWorkItemCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`AgentWorkItemCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.agent_id` | `string` | yes | Which agent owns it. A known id the planner has a template for - `onboarding`, `dialer_setup`, `sequencer_setup`, `campaign_run`, `voice_setup`, `marketplace`, `dev_setup` - or a free-form value, for which the planner falls back to its `full` template. Left as an open string for that reason: an enum here would reject the ad-hoc case the planner explicitly supports. |
+| `body.goal` | `string` | yes | What the agent should achieve. min length 1 |
+| `body.title` | `string` | yes | min length 1, max length 500 |
+| `body.entry_point` | `string \| null` | no | Per-session override. Unset, the planner reads the org's own signup entry point as the long-term truth - so omitting this is usually right. |
+| `body.page` | `string \| null` | no | max length 500 |
+| `body.platform` | `"whatsapp" \| "slack" \| "roam" \| "imessage" \| null` | no |  |
+| `body.seed_message` | `string \| null` | no | First user message, so the session opens on the real request. |
+| `body.session_title` | `string \| null` | no | Sidebar title. Defaults to `title`. |
+| `body.skill_mode` | `string \| null` | no | `web_search`, `deep_thinking` or `research`. Biases the planner prompt and model tier. Unknown values are IGNORED by the planner rather than rejected, which is why this is not an enum. |
+| `body.source` | `"canvas" \| "bridge" \| null` | no |  |
+| `body.subject_account_id` | `string \| null` | no | Bind the session to a company. |
+| `body.subject_campaign_id` | `string \| null` | no | Bind the session to a campaign. |
+| `body.user_email` | `string \| null` | no | Whose work item this is. Defaults to the identity the key was minted under. |
+| `body.visibility` | `"shared" \| "private"` | no | `private` (default) or `shared` org-wide. The default is the safe one: work started through an API key is not visible to the whole org unless asked for. default `"private"` |
+
+**Returns** `ApiResponse_AgentWorkItem_`: the envelope `{ data: AgentWorkItem, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentWorkItem` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `agent_id` | `string \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `goal` | `string \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `session_id` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `title` | `string \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+| `visibility` | `string \| null` | no |  |
+| `work_item_id` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.agents.createAgentWorkItem({ body: { agent_id: "id", goal: "example", title: "Example" } });
+```
+
+---
+
+<a id="op-decideagentoperatorapproval"></a>
+
+### `g8.api.agents.decideAgentOperatorApproval(input)`
+
+**Decide Agent Operator Approval**
+
+- HTTP: `POST /api/v1/agent/operators/{operator}/approvals/{task_id}/decide`
+- operationId: `decide_agent_operator_approval_agent_operators__operator__approvals__task_id__decide_post` (also callable as `g8.api.call("decide_agent_operator_approval_agent_operators__operator__approvals__task_id__decide_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `workflows:run`
+
+Approve or reject a fix this operator proposed.
+
+`approved` RUNS THE FIX: the operator executes its proposed remediation
+against your data, then records the result. `rejected` records the
+decision and runs nothing. Needs OPERATOR_MANAGE, the same governance gate
+as the trust dials, because this authorises execution.
+
+A task that is not an open approval for this operator is a 404.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+| `path.task_id` | `string` | yes | The approval task id. |
+| `body` | `OperatorApprovalDecisionRequest` | yes | Request body; fields below. |
+
+Body fields (`OperatorApprovalDecisionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.resolution` | `"approved" \| "rejected"` | yes | `approved` EXECUTES the finding's proposed fix against your data; `rejected` records the decision and executes nothing. |
+| `body.params` | `Record<string, string> \| null` | no | Values a fix needs that the operator could not decide for you, e.g. `{"target_user": "<user id>"}`. Omit for a fully-specified fix. A value the fix refuses is a 400 naming the field, and the task stays open. |
+
+**Returns** `ApiResponse_OperatorPayload_`: the envelope `{ data: OperatorPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.agents.decideAgentOperatorApproval({
+  path: { operator: "example", task_id: "id" },
+  body: { resolution: "approved" },
+});
+```
+
+---
+
+<a id="op-deleteagentsession"></a>
+
+### `g8.api.agents.deleteAgentSession(input)`
+
+**Delete Agent Session**
+
+- HTTP: `DELETE /api/v1/agent/sessions/{session_id}`
+- operationId: `delete_agent_session_agent_sessions__session_id__delete` (also callable as `g8.api.call("delete_agent_session_agent_sessions__session_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `workflows:delete`
+
+Delete a session. Owner only - the internal handler enforces that.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.session_id` | `string` | yes | Session 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.agents.deleteAgentSession({ path: { session_id: "id" } });
+```
+
+---
+
+<a id="op-endagentsessionvoice"></a>
+
+### `g8.api.agents.endAgentSessionVoice(input)`
+
+**End Agent Session Voice**
+
+- HTTP: `DELETE /api/v1/agent/sessions/{session_id}/voice/{voice_id}`
+- operationId: `end_agent_session_voice_agent_sessions__session_id__voice__voice_id__delete` (also callable as `g8.api.call("end_agent_session_voice_agent_sessions__session_id__voice__voice_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `workflows:delete`
+
+Stop a live voice session, and stop the meter.
+
+This is the one that costs money NOT to call. Ending is the only thing that
+stops the charge short of the ceiling, so treat it as part of the start
+call rather than as cleanup.
+
+The CONVERSATION survives - this ends the audio session, not the chat. The
+transcript stays readable through `GET /agent/sessions/{session_id}/state`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.session_id` | `string` | yes | Session id (UUID). |
+| `path.voice_id` | `string` | yes | Voice session id (UUID) from the start call. |
+
+**Returns** `ApiResponse_AgentSessionStatePayload_`: the envelope `{ data: AgentSessionStatePayload, ... }`. `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.agents.endAgentSessionVoice({ path: { session_id: "id", voice_id: "id" } });
+```
+
+---
+
+<a id="op-getagentdiscovery"></a>
+
+### `g8.api.agents.getAgentDiscovery(input?)`
+
+**Get Agent Discovery**
+
+- HTTP: `GET /api/v1/agent/onboarding/discovery`
+- operationId: `get_agent_discovery_agent_onboarding_discovery_get` (also callable as `g8.api.call("get_agent_discovery_agent_onboarding_discovery_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+The whole discovery record, plus an honest coverage report.
+
+EVERY field comes back, answered or not - an unanswered one carries
+`status: "open"` rather than being absent, so a caller renders a stable
+list instead of one that grows as the interview proceeds.
+
+`coverage` is the part worth reading: `open_musts` names what still blocks
+a launch, `amber_fields` names the working assumptions, and `can_launch` is
+the single boolean. It is not a percentage, on purpose - a framework with
+silent gaps is worse than no framework, because the gaps become confident
+copy three weeks later.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OnboardingPayload_`: the envelope `{ data: OnboardingPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentDiscovery();
+```
+
+---
+
+<a id="op-getagentdiscoverycampaignbrief"></a>
+
+### `g8.api.agents.getAgentDiscoveryCampaignBrief(input?)`
+
+**Get Agent Discovery Campaign Brief**
+
+- HTTP: `GET /api/v1/agent/onboarding/discovery/campaign-brief`
+- operationId: `get_agent_discovery_campaign_brief_agent_onboarding_discovery_campaign_brief_get` (also callable as `g8.api.call("get_agent_discovery_campaign_brief_agent_onboarding_discovery_campaign_brief_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+The campaign brief the record would produce. A PREVIEW - it writes
+nothing.
+
+Deterministic and LLM-free: running it again after two more answers gives
+the same document plus two facts, not a differently-worded one. That is
+what makes it safe to poll while the interview is still going.
+
+It never fills a gap to look finished. `open_musts` and `assumptions` come
+back alongside the copy, because a brief that reads as complete while four
+must-answer questions are open is how a silent gap becomes a confident
+wrong campaign.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OnboardingPayload_`: the envelope `{ data: OnboardingPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentDiscoveryCampaignBrief();
+```
+
+---
+
+<a id="op-getagentdiscoveryreport"></a>
+
+### `g8.api.agents.getAgentDiscoveryReport(input?)`
+
+**Get Agent Discovery Report**
+
+- HTTP: `GET /api/v1/agent/onboarding/discovery/report`
+- operationId: `get_agent_discovery_report_agent_onboarding_discovery_report_get` (also callable as `g8.api.call("get_agent_discovery_report_agent_onboarding_discovery_report_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+The closing report: what is filled, which MUSTs are still open, what was
+inferred rather than answered.
+
+Deliberately not a score. The inferred fields are flagged rather than
+counted, because the useful question at the end of an interview is "what
+did we make up", not "how far did we get".
+
+**Input**: none.
+
+**Returns** `ApiResponse_OnboardingPayload_`: the envelope `{ data: OnboardingPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentDiscoveryReport();
+```
+
+---
+
+<a id="op-getagentmemory"></a>
+
+### `g8.api.agents.getAgentMemory(input?)`
+
+**Get Agent Memory**
+
+- HTTP: `GET /api/v1/agent/memory`
+- operationId: `get_agent_memory_agent_memory_get` (also callable as `g8.api.call("get_agent_memory_agent_memory_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+What the agent has learned and carries between sessions.
+
+Returned open-shaped: memory is planner state that changes as the platform
+does, and on an oversight surface a dropped field reads as an agent knowing
+less than it does.
+
+**Input**: none.
+
+**Returns** `ApiResponse_AgentPayload_`: the envelope `{ data: AgentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentMemory();
+```
+
+---
+
+<a id="op-getagentoperatingmodel"></a>
+
+### `g8.api.agents.getAgentOperatingModel(input?)`
+
+**Get Agent Operating Model**
+
+- HTTP: `GET /api/v1/agent/operators/operating-model`
+- operationId: `get_agent_operating_model_agent_operators_operating_model_get` (also callable as `g8.api.call("get_agent_operating_model_agent_operators_operating_model_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+The organisation's operating model: which motions it runs, so operators
+know what "normal" looks like here.
+
+Read this before writing it. The write is a whole-document replace.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OperatorPayload_`: the envelope `{ data: OperatorPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentOperatingModel();
+```
+
+---
+
+<a id="op-getagentoperatorcatalog"></a>
+
+### `g8.api.agents.getAgentOperatorCatalog(input)`
+
+**Get Agent Operator Catalog**
+
+- HTTP: `GET /api/v1/agent/operators/{operator}/catalog`
+- operationId: `get_agent_operator_catalog_agent_operators__operator__catalog_get` (also callable as `g8.api.call("get_agent_operator_catalog_agent_operators__operator__catalog_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Everything this operator is CAPABLE of, whether or not it is enabled.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+
+**Returns** `ApiResponse_OperatorPayload_`: the envelope `{ data: OperatorPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentOperatorCatalog({ path: { operator: "example" } });
+```
+
+---
+
+<a id="op-getagentoperatorfeedbacksummary"></a>
+
+### `g8.api.agents.getAgentOperatorFeedbackSummary(input)`
+
+**Get Agent Operator Feedback Summary**
+
+- HTTP: `GET /api/v1/agent/operators/{operator}/feedback/summary`
+- operationId: `get_agent_operator_feedback_summary_agent_operators__operator__feedback_summary_get` (also callable as `g8.api.call("get_agent_operator_feedback_summary_agent_operators__operator__feedback_summary_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+What people have said about this operator, in aggregate.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+
+**Returns** `ApiResponse_OperatorPayload_`: the envelope `{ data: OperatorPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentOperatorFeedbackSummary({ path: { operator: "example" } });
+```
+
+---
+
+<a id="op-getagentoperatorforapprovaltask"></a>
+
+### `g8.api.agents.getAgentOperatorForApprovalTask(input)`
+
+**Get Agent Operator For Approval Task**
+
+- HTTP: `GET /api/v1/agent/operators/approvals/{task_id}/operator`
+- operationId: `get_agent_operator_for_approval_task_agent_operators_approvals__task_id__operator_get` (also callable as `g8.api.call("get_agent_operator_for_approval_task_agent_operators_approvals__task_id__operator_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Which operator raised this approval task.
+
+The bridge between an approval sitting in someone's queue and the operator
+whose dial produced it - so a caller can look at the right scorecard before
+deciding, and can leave feedback against the right operator afterwards.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes | Operator approval task id. |
+
+**Returns** `ApiResponse_OperatorPayload_`: the envelope `{ data: OperatorPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentOperatorForApprovalTask({ path: { task_id: "id" } });
+```
+
+---
+
+<a id="op-getagentoperatorhealth"></a>
+
+### `g8.api.agents.getAgentOperatorHealth(input)`
+
+**Get Agent Operator Health**
+
+- HTTP: `GET /api/v1/agent/operators/{operator}/health`
+- operationId: `get_agent_operator_health_agent_operators__operator__health_get` (also callable as `g8.api.call("get_agent_operator_health_agent_operators__operator__health_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+This operator's snapshot of the organisation it watches.
+
+Open-shaped: each operator reports the checks IT runs, and the set grows
+with the product. A pinned mirror would silently drop a check, and on a
+health surface a missing check reads as a passing one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+
+**Returns** `ApiResponse_OperatorPayload_`: the envelope `{ data: OperatorPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentOperatorHealth({ path: { operator: "example" } });
+```
+
+---
+
+<a id="op-getagentoperatorrecipient"></a>
+
+### `g8.api.agents.getAgentOperatorRecipient(input)`
+
+**Get Agent Operator Recipient**
+
+- HTTP: `GET /api/v1/agent/operators/{operator}/recipient`
+- operationId: `get_agent_operator_recipient_agent_operators__operator__recipient_get` (also callable as `g8.api.call("get_agent_operator_recipient_agent_operators__operator__recipient_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Who currently receives this operator's alerts and owns its approvals.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+
+**Returns** `ApiResponse_OperatorPayload_`: the envelope `{ data: OperatorPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentOperatorRecipient({ path: { operator: "example" } });
+```
+
+---
+
+<a id="op-getagentoperatorscorecard"></a>
+
+### `g8.api.agents.getAgentOperatorScorecard(input)`
+
+**Get Agent Operator Scorecard**
+
+- HTTP: `GET /api/v1/agent/operators/{operator}/scorecard`
+- operationId: `get_agent_operator_scorecard_agent_operators__operator__scorecard_get` (also callable as `g8.api.call("get_agent_operator_scorecard_agent_operators__operator__scorecard_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Has this operator been right, per skill.
+
+The number to read before raising a dial. Raising autonomy on a skill with
+a bad scorecard is how unattended work becomes unattended damage.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+
+**Returns** `ApiResponse_OperatorPayload_`: the envelope `{ data: OperatorPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentOperatorScorecard({ path: { operator: "example" } });
+```
+
+---
+
+<a id="op-getagentoperatorstatus"></a>
+
+### `g8.api.agents.getAgentOperatorStatus(input)`
+
+**Get Agent Operator Status**
+
+- HTTP: `GET /api/v1/agent/operators/{operator}/status`
+- operationId: `get_agent_operator_status_agent_operators__operator__status_get` (also callable as `g8.api.call("get_agent_operator_status_agent_operators__operator__status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Is this operator on, and has it ever run.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+
+**Returns** `ApiResponse_OperatorPayload_`: the envelope `{ data: OperatorPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentOperatorStatus({ path: { operator: "example" } });
+```
+
+---
+
+<a id="op-getagentoperatorssummary"></a>
+
+### `g8.api.agents.getAgentOperatorsSummary(input?)`
+
+**Get Agent Operators Summary**
+
+- HTTP: `GET /api/v1/agent/operators/summary`
+- operationId: `get_agent_operators_summary_agent_operators_summary_get` (also callable as `g8.api.call("get_agent_operators_summary_agent_operators_summary_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+One digest across the whole bench.
+
+Finding counts here are DISTINCT, not the sum of the per-operator numbers
+from `GET /agent/operators`. Shared findings legitimately appear in several
+operators' caches, and adding the cards up counts them more than once - the
+app's own banner did exactly that before this was split out.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OperatorPayload_`: the envelope `{ data: OperatorPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentOperatorsSummary();
+```
+
+---
+
+<a id="op-getagentoversight"></a>
+
+### `g8.api.agents.getAgentOversight(input?)`
+
+**Get Agent Oversight**
+
+- HTTP: `GET /api/v1/agent/oversight`
+- operationId: `get_agent_oversight_agent_oversight_get` (also callable as `g8.api.call("get_agent_oversight_agent_oversight_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+What your agents need from a person, and what they did without asking.
+
+Three groups in one read: `approvals` (work stopped on a decision - each
+row carries what `POST /agent/approvals/{approval_id}/decide` needs),
+`blockers` (work stopped for another reason, with why) and
+`autonomous_fixes` (changes made on your behalf).
+
+AN EMPTY GROUP SAYS WHY. Read `states`: `ready` means the read worked and
+there is nothing, `unavailable` means the read failed, `not_recorded`
+means nothing is ever recorded there for this org (no skill is dialled to
+act on its own). Every group is capped at `limit` and says so in `bounds`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.limit` | `integer` | no | Max rows PER GROUP. default `50` |
+| `query.fix_window_hours` | `integer` | no | How far back autonomous fixes are read. default `24` |
+
+**Returns** `ApiResponse_AgentConversationPayload_`: the envelope `{ data: AgentConversationPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentOversight();
+```
+
+---
+
+<a id="op-getagentproactiveopener"></a>
+
+### `g8.api.agents.getAgentProactiveOpener(input?)`
+
+**Get Agent Proactive Opener**
+
+- HTTP: `GET /api/v1/agent/proactive-opener`
+- operationId: `get_agent_proactive_opener_agent_proactive_opener_get` (also callable as `g8.api.call("get_agent_proactive_opener_agent_proactive_opener_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+What the agent would open a conversation with, unprompted.
+
+A read - it computes a suggestion and starts nothing.
+
+**Input**: none.
+
+**Returns** `ApiResponse_AgentPayload_`: the envelope `{ data: AgentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentProactiveOpener();
+```
+
+---
+
+<a id="op-getagentpushbackevidence"></a>
+
+### `g8.api.agents.getAgentPushbackEvidence(input?)`
+
+**Get Agent Pushback Evidence**
+
+- HTTP: `GET /api/v1/agent/evidence/pushback`
+- operationId: `get_agent_pushback_evidence_agent_evidence_pushback_get` (also callable as `g8.api.call("get_agent_pushback_evidence_agent_evidence_pushback_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Where the agent was overruled, and on what.
+
+The oversight signal worth acting on: it shows which of the agent's
+suggestions humans rejected, which is how a customer tunes it rather than
+turning it off.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.window_days` | `integer` | no | Lookback window in days. default `30` |
+
+**Returns** `ApiResponse_AgentPayload_`: the envelope `{ data: AgentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentPushbackEvidence();
+```
+
+---
+
+<a id="op-getagentsession"></a>
+
+### `g8.api.agents.getAgentSession(input)`
+
+**Get Agent Session**
+
+- HTTP: `GET /api/v1/agent/sessions/{session_id}`
+- operationId: `get_agent_session_agent_sessions__session_id__get` (also callable as `g8.api.call("get_agent_session_agent_sessions__session_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Read one session, including its messages.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.session_id` | `string` | yes | Session id. |
+
+**Returns** `ApiResponse_AgentSession_`: the envelope `{ data: AgentSession, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentSession` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_at` | `string (date-time) \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `is_pinned` | `boolean \| null` | no |  |
+| `mode` | `string \| null` | no | Session mode, e.g. `general`. |
+| `title` | `string \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentSession({ path: { session_id: "id" } });
+```
+
+---
+
+<a id="op-getagentsessionstate"></a>
+
+### `g8.api.agents.getAgentSessionState(input)`
+
+**Get Agent Session State**
+
+- HTTP: `GET /api/v1/agent/sessions/{session_id}/state`
+- operationId: `get_agent_session_state_agent_sessions__session_id__state_get` (also callable as `g8.api.call("get_agent_session_state_agent_sessions__session_id__state_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Everything needed to render one session from cold.
+
+THREE sources in one answer, and the difference between them matters:
+`messages` are the chat bubbles, `steps` are what the agent actually did
+(tool calls, reasoning summaries) and `work_item_status` is whether it is
+still going. A session driven by a work item has richer `steps` than
+`messages`, and a plain chat has only `messages` - so a client that renders
+only one of them will show an empty conversation for half the sessions.
+
+404s on a session the caller cannot see, rather than 403 - existence is not
+leaked by distinguishing the two.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.session_id` | `string` | yes | Session id (UUID). |
+
+**Returns** `ApiResponse_AgentSessionStatePayload_`: the envelope `{ data: AgentSessionStatePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentSessionState({ path: { session_id: "id" } });
+```
+
+---
+
+<a id="op-getagentsessionvoicecapability"></a>
+
+### `g8.api.agents.getAgentSessionVoiceCapability(input)`
+
+**Get Agent Session Voice Capability**
+
+- HTTP: `GET /api/v1/agent/sessions/{session_id}/voice`
+- operationId: `get_agent_session_voice_capability_agent_sessions__session_id__voice_get` (also callable as `g8.api.call("get_agent_session_voice_capability_agent_sessions__session_id__voice_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Can voice be used on THIS session.
+
+Differs from the workspace answer by also checking the caller owns the
+session, so it is the one to ask before showing a microphone on a specific
+conversation.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.session_id` | `string` | yes | Session id (UUID). |
+
+**Returns** `ApiResponse_AgentSessionStatePayload_`: the envelope `{ data: AgentSessionStatePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentSessionVoiceCapability({ path: { session_id: "id" } });
+```
+
+---
+
+<a id="op-getagentvoicecapability"></a>
+
+### `g8.api.agents.getAgentVoiceCapability(input?)`
+
+**Get Agent Voice Capability**
+
+- HTTP: `GET /api/v1/agent/sessions/voice/capability`
+- operationId: `get_agent_voice_capability_agent_sessions_voice_capability_get` (also callable as `g8.api.call("get_agent_voice_capability_agent_sessions_voice_capability_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Can this workspace use voice at all, and what does it cost.
+
+The org-wide answer, with indicative pricing - ask this before building a
+voice affordance into a UI. The per-session twin
+(`GET /agent/sessions/{session_id}/voice`) answers the same question for one
+conversation and additionally checks the caller owns it.
+
+`available: false` comes with a `reason`, so a client can say WHY rather
+than hiding the control.
+
+**Input**: none.
+
+**Returns** `ApiResponse_AgentSessionStatePayload_`: the envelope `{ data: AgentSessionStatePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.getAgentVoiceCapability();
+```
+
+---
+
+<a id="op-listagentoperatoractions"></a>
+
+### `g8.api.agents.listAgentOperatorActions(input)`
+
+**List Agent Operator Actions**
+
+- HTTP: `GET /api/v1/agent/operators/{operator}/actions`
+- operationId: `list_agent_operator_actions_agent_operators__operator__actions_get` (also callable as `g8.api.call("list_agent_operator_actions_agent_operators__operator__actions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+The action descriptors behind this operator's skills.
+
+Static and org-independent - the same answer for every organisation. It is
+the definition of what each action does and how reversible it is, which is
+what the trust-dial ceiling is computed from.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+
+**Returns** `ApiResponse_OperatorListPayload_`: the envelope `{ data: OperatorListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OperatorListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.listAgentOperatorActions({ path: { operator: "example" } });
+```
+
+---
+
+<a id="op-listagentoperatoractivity"></a>
+
+### `g8.api.agents.listAgentOperatorActivity(input)`
+
+**List Agent Operator Activity**
+
+- HTTP: `GET /api/v1/agent/operators/{operator}/activity`
+- operationId: `list_agent_operator_activity_agent_operators__operator__activity_get` (also callable as `g8.api.call("list_agent_operator_activity_agent_operators__operator__activity_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+What this operator actually DID - decided approvals and remediations.
+
+Findings are what it saw; this is what it changed. The audit trail for
+unattended work, and the only place that distinguishes the two.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+| `query.limit` | `integer` | no | How many history rows to return. The app's own default is 50 and it declares no ceiling; a bound is added here because an unbounded limit on a public contract is a denial-of-service parameter. default `50` |
+
+**Returns** `ApiResponse_OperatorListPayload_`: the envelope `{ data: OperatorListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OperatorListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.listAgentOperatorActivity({ path: { operator: "example" } });
+```
+
+---
+
+<a id="op-listagentoperatoractivityrecords"></a>
+
+### `g8.api.agents.listAgentOperatorActivityRecords(input)`
+
+**List Agent Operator Activity Records**
+
+- HTTP: `GET /api/v1/agent/operators/{operator}/activity/{task_id}/records`
+- operationId: `list_agent_operator_activity_records_agent_operators__operator__activity__task_id__records_get` (also callable as `g8.api.call("list_agent_operator_activity_records_agent_operators__operator__activity__task_id__records_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Which records one activity entry touched.
+
+The row-level detail behind a single thing the operator did: what it
+changed, not just that it changed something.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+| `path.task_id` | `string` | yes | Task id from the activity list. |
+
+**Returns** `ApiResponse_OperatorListPayload_`: the envelope `{ data: OperatorListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OperatorListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.listAgentOperatorActivityRecords({ path: { operator: "example", task_id: "id" } });
+```
+
+---
+
+<a id="op-listagentoperatorapprovalsources"></a>
+
+### `g8.api.agents.listAgentOperatorApprovalSources(input?)`
+
+**List Agent Operator Approval Sources**
+
+- HTTP: `GET /api/v1/agent/operators/approvals/sources`
+- operationId: `list_agent_operator_approval_sources_agent_operators_approvals_sources_get` (also callable as `g8.api.call("list_agent_operator_approval_sources_agent_operators_approvals_sources_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Where operator approval tasks come from.
+
+The vocabulary behind `GET /agent/operators/{operator}/findings` - what
+kinds of thing raise an approval in the first place.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OperatorListPayload_`: the envelope `{ data: OperatorListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OperatorListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.listAgentOperatorApprovalSources();
+```
+
+---
+
+<a id="op-listagentoperatorcollections"></a>
+
+### `g8.api.agents.listAgentOperatorCollections(input)`
+
+**List Agent Operator Collections**
+
+- HTTP: `GET /api/v1/agent/operators/{operator}/collections`
+- operationId: `list_agent_operator_collections_agent_operators__operator__collections_get` (also callable as `g8.api.call("list_agent_operator_collections_agent_operators__operator__collections_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+The knowledge collections this operator reasons from.
+
+Slug, name and a one-line summary only. The BODIES are never returned -
+they are graph8-managed and locked, and the app does not expose them
+either. This is not a gap in the proxy.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+
+**Returns** `ApiResponse_OperatorListPayload_`: the envelope `{ data: OperatorListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OperatorListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.listAgentOperatorCollections({ path: { operator: "example" } });
+```
+
+---
+
+<a id="op-listagentoperatorfindings"></a>
+
+### `g8.api.agents.listAgentOperatorFindings(input)`
+
+**List Agent Operator Findings**
+
+- HTTP: `GET /api/v1/agent/operators/{operator}/findings`
+- operationId: `list_agent_operator_findings_agent_operators__operator__findings_get` (also callable as `g8.api.call("list_agent_operator_findings_agent_operators__operator__findings_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+What this operator has found and classified, right now.
+
+The output of unattended work. Findings are what a `DETECT` dial produces;
+a `PROPOSE` dial turns some of them into approval tasks a person decides.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+
+**Returns** `ApiResponse_OperatorListPayload_`: the envelope `{ data: OperatorListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OperatorListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.listAgentOperatorFindings({ path: { operator: "example" } });
+```
+
+---
+
+<a id="op-listagentoperatorskills"></a>
+
+### `g8.api.agents.listAgentOperatorSkills(input)`
+
+**List Agent Operator Skills**
+
+- HTTP: `GET /api/v1/agent/operators/{operator}/skills`
+- operationId: `list_agent_operator_skills_agent_operators__operator__skills_get` (also callable as `g8.api.call("list_agent_operator_skills_agent_operators__operator__skills_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Each skill this operator has, and how far it may currently go.
+
+The source of the `skill_key` values the trust-dial write accepts, and the
+place to read back what a dial actually RESOLVED to after the risk cap was
+applied.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+
+**Returns** `ApiResponse_OperatorListPayload_`: the envelope `{ data: OperatorListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OperatorListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.listAgentOperatorSkills({ path: { operator: "example" } });
+```
+
+---
+
+<a id="op-listagentoperators"></a>
+
+### `g8.api.agents.listAgentOperators(input?)`
+
+**List Agent Operators**
+
+- HTTP: `GET /api/v1/agent/operators`
+- operationId: `list_agent_operators_agent_operators_get` (also callable as `g8.api.call("list_agent_operators_agent_operators_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Every operator on the bench, with whether it is switched on for you.
+
+The starting point for this surface: it carries each operator's catalog
+metadata and its live status - enabled, whether it has ever run, and how
+many findings it is holding.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OperatorListPayload_`: the envelope `{ data: OperatorListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OperatorListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.listAgentOperators();
+```
+
+---
+
+<a id="op-listagentsessions"></a>
+
+### `g8.api.agents.listAgentSessions(input?)`
+
+**List Agent Sessions**
+
+- HTTP: `GET /api/v1/agent/sessions`
+- operationId: `list_agent_sessions_agent_sessions_get` (also callable as `g8.api.call("list_agent_sessions_agent_sessions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Sessions owned by, or shared with, the principal behind this key.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.mode` | `string \| null` | no | Filter to one session mode. |
+| `query.limit` | `integer` | no | Page size (max 200). default `50` |
+| `query.offset` | `integer` | no | Rows to skip. default `0` |
+
+**Returns** `ApiResponse_AgentSessionListResponse_`: the envelope `{ data: AgentSessionListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentSessionListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `sessions` | `Array<AgentSession>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.listAgentSessions();
+```
+
+---
+
+<a id="op-listagentspecialists"></a>
+
+### `g8.api.agents.listAgentSpecialists(input?)`
+
+**List Agent Specialists**
+
+- HTTP: `GET /api/v1/agent/specialists`
+- operationId: `list_agent_specialists_agent_specialists_get` (also callable as `g8.api.call("list_agent_specialists_agent_specialists_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+The sub-agents available to be delegated to.
+
+The bench: who each specialist is, what it is for, and whether it backs the
+Chief of Staff. Static and the same for every organisation - it is the
+catalogue of what the platform can delegate to, not what YOUR org has
+configured.
+
+Read it to learn the `agent_id` values `POST /agent/work-items` accepts as
+its planner template. An unknown id there falls back to the general planner
+rather than failing, which is why that field is an open string - this is the
+list that stops a caller relying on that fallback by accident.
+
+**Input**: none.
+
+**Returns** `ApiResponse_AgentBenchListPayload_`: the envelope `{ data: AgentBenchListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentBenchListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.listAgentSpecialists();
+```
+
+---
+
+<a id="op-listagentworkitems"></a>
+
+### `g8.api.agents.listAgentWorkItems(input?)`
+
+**List Agent Work Items**
+
+- HTTP: `GET /api/v1/agent/work-items`
+- operationId: `list_agent_work_items_agent_work_items_get` (also callable as `g8.api.call("list_agent_work_items_agent_work_items_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Work items the caller can see.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.statuses` | `Array<string> \| null` | no | Status filter, REPEATABLE: `?statuses=running&statuses=queued`. Repeated rather than comma-joined, matching the app - a comma in a status would otherwise split it. |
+| `query.agent_id` | `string \| null` | no | Filter to one agent. |
+| `query.include_shared` | `boolean` | no | Include org-wide shared items as well as the caller's own. True by default, matching the app - set false to see only your own. default `true` |
+| `query.limit` | `integer` | no | default `100` |
+| `query.offset` | `integer` | no | default `0` |
+
+**Returns** `ApiResponse_AgentWorkItemList_`: the envelope `{ data: AgentWorkItemList, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentWorkItemList` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `total` | `integer` | no | default `0` |
+| `work_items` | `Array<AgentWorkItem>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.listAgentWorkItems();
+```
+
+---
+
+<a id="op-loadcopilotintentcontext"></a>
+
+### `g8.api.agents.loadCopilotIntentContext(input)`
+
+**Load Copilot Intent Context**
+
+- HTTP: `POST /api/v1/copilot/context/load`
+- operationId: `load_copilot_intent_context_copilot_context_load_post` (also callable as `g8.api.call("load_copilot_intent_context_copilot_context_load_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Open a Copilot session already briefed on one buyer-intent keyword.
+
+Returns `session_id`. The session is seeded with the keyword's detail (and
+the company or contact, if given), so the first question can be about it
+without restating it. No model runs here.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CopilotContextLoadRequest` | yes | Request body; fields below. |
+
+Body fields (`CopilotContextLoadRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.keyword_id` | `string (uuid)` | yes | The buyer-intent keyword to open a conversation about. |
+| `body.company_id` | `integer \| null` | no | Narrow the context to one company. |
+| `body.contact_id` | `integer \| null` | no | Narrow the context to one contact. |
+
+**Returns** `ApiResponse_AgentConversationPayload_`: the envelope `{ data: AgentConversationPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.loadCopilotIntentContext({ body: { keyword_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-markagentsessionread"></a>
+
+### `g8.api.agents.markAgentSessionRead(input)`
+
+**Mark Agent Session Read**
+
+- HTTP: `PUT /api/v1/agent/sessions/{session_id}/read`
+- operationId: `mark_agent_session_read_agent_sessions__session_id__read_put` (also callable as `g8.api.call("mark_agent_session_read_agent_sessions__session_id__read_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Mark messages read up to a COUNT, not a flag.
+
+A count higher than the session actually holds is refused with 409 rather
+than accepted. That looks strict until you consider what accepting it does:
+a stale client claiming to have read eleven messages when there are nine
+would mark the next two read before anyone saw them, and the customer would
+never be told the agent had replied.
+
+The app answers 204 with no body; this returns the usual envelope so a
+generated SDK has one response shape across the surface.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.session_id` | `string` | yes | Session id (UUID). |
+| `body` | `SessionReadRequest` | yes | Request body; fields below. |
+
+Body fields (`SessionReadRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.message_count` | `integer` | yes | How many messages the caller has actually seen. NOT a flag: the server refuses a count higher than the session holds with a 409, because a client claiming to have read messages that do not exist yet is a stale client, and silently accepting it would mark a later real message read before anyone saw it. min 0 |
+
+**Returns** `ApiResponse_AgentSessionStatePayload_`: the envelope `{ data: AgentSessionStatePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.markAgentSessionRead({ path: { session_id: "id" }, body: { message_count: 0 } });
+```
+
+---
+
+<a id="op-openagentdiscovery"></a>
+
+### `g8.api.agents.openAgentDiscovery(input?)`
+
+**Open Agent Discovery**
+
+- HTTP: `POST /api/v1/agent/onboarding/discovery/open`
+- operationId: `open_agent_discovery_agent_onboarding_discovery_open_post` (also callable as `g8.api.call("open_agent_discovery_agent_onboarding_discovery_open_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Start the interview: show what the agent already worked out, and ask
+where it is wrong.
+
+Takes no body. Degrades gracefully when nothing is readable yet - a
+brand-new org's site scrape lands minutes after signup, and the app decided
+a routing question is a better opener than a spinner.
+
+A VIEW never enrols an org into a kickoff: proposals are only STAGED for an
+org that already has an onboarding room, which is what stops one visit
+giving an established org a permanent door onto an empty conversation.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OnboardingPayload_`: the envelope `{ data: OnboardingPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.openAgentDiscovery();
+```
+
+---
+
+<a id="op-pinagentsession"></a>
+
+### `g8.api.agents.pinAgentSession(input)`
+
+**Pin Agent Session**
+
+- HTTP: `POST /api/v1/agent/sessions/{session_id}/pin`
+- operationId: `pin_agent_session_agent_sessions__session_id__pin_post` (also callable as `g8.api.call("pin_agent_session_agent_sessions__session_id__pin_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Pin or unpin a session. Owner only.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.session_id` | `string` | yes | Session id. |
+| `body` | `AgentSessionPinRequest` | yes | Request body; fields below. |
+
+Body fields (`AgentSessionPinRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.is_pinned` | `boolean` | yes | True to pin, false to unpin. |
+
+**Returns** `ApiResponse_AgentSession_`: the envelope `{ data: AgentSession, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentSession` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_at` | `string (date-time) \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `is_pinned` | `boolean \| null` | no |  |
+| `mode` | `string \| null` | no | Session mode, e.g. `general`. |
+| `title` | `string \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.pinAgentSession({ path: { session_id: "id" }, body: { is_pinned: true } });
+```
+
+---
+
+<a id="op-postagentchat"></a>
+
+### `g8.api.agents.postAgentChat(input)`
+
+**Post Agent Chat**
+
+- HTTP: `POST /api/v1/agent/chat`
+- operationId: `post_agent_chat_agent_chat_post` (also callable as `g8.api.call("post_agent_chat_agent_chat_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `workflows:run`
+
+Say something to the agent and get its answer.
+
+`kind` in the answer says which way the turn went: `chat` is a reply in
+`message`; `work_item` means the agent read the message as a job and
+STARTED it - `work_item_id` is the work item, and whether its workflow
+actually launched is in `workflow_started`.
+
+Each turn runs a model and is charged. Omit `session_id` to start a new
+session.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `AgentChatRequest` | yes | Request body; fields below. |
+
+Body fields (`AgentChatRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.attachment_ids` | `Array<string>` | no | Uploaded file ids to attach, each at most once. max items 20 |
+| `body.client_turn_id` | `string (uuid) \| null` | no | Your own id for this turn, so a retry is recognised as the same turn rather than said twice. Needs an existing `session_id`. |
+| `body.mentions` | `Array<Record<string, unknown>> \| null` | no | @-mentions from `POST /agent/mention-search`, passed through as returned (`id`, `category`, `display_name`, ...). |
+| `body.message` | `string` | no | What you say to the agent. Required unless you attach a file. default `""`, max length 10000 |
+| `body.mode` | `string \| null` | no | Bias the agent: `web_search`, `deep_thinking` or `research`. Left open, as the app leaves it: an unknown mode is ignored rather than refused. |
+| `body.page` | `string \| null` | no | Where the user is in your product, so 'this' and 'here' resolve. |
+| `body.session_id` | `string (uuid) \| null` | no | Continue this session. Omit to start a new one; the answer carries its `session_id`. |
+| `body.subject_account_id` | `string \| null` | no | Bind a NEW session to this account. Ignored for an existing one. |
+| `body.subject_campaign_id` | `string \| null` | no | Bind a NEW session to this campaign. Ignored for an existing one. |
+
+**Returns** `ApiResponse_AgentConversationPayload_`: the envelope `{ data: AgentConversationPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.agents.postAgentChat({ body: {} });
+```
+
+---
+
+<a id="op-postagentonboardingcatchup"></a>
+
+### `g8.api.agents.postAgentOnboardingCatchup(input)`
+
+**Post Agent Onboarding Catchup**
+
+- HTTP: `POST /api/v1/agent/onboarding/catchup`
+- operationId: `post_agent_onboarding_catchup_agent_onboarding_catchup_post` (also callable as `g8.api.call("post_agent_onboarding_catchup_agent_onboarding_catchup_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Post ONE batched summary of what finished while the customer was away.
+
+IDEMPOTENT by watermark: a marker on the previous catch-up message is the
+high-water mark, so a repeat call posts nothing and comes back
+`posted: false`. Below the app's minimum card count it is also a no-op - a
+single completed card does not need a summary.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `OnboardingCatchupRequest` | yes | Request body; fields below. |
+
+Body fields (`OnboardingCatchupRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.session_id` | `string` | yes | The proactive-setup canvas session id. |
+
+**Returns** `ApiResponse_OnboardingPayload_`: the envelope `{ data: OnboardingPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.postAgentOnboardingCatchup({ body: { session_id: "id" } });
+```
+
+---
+
+<a id="op-postagentsessionmessage"></a>
+
+### `g8.api.agents.postAgentSessionMessage(input)`
+
+**Post Agent Session Message**
+
+- HTTP: `POST /api/v1/agent/sessions/{session_id}/messages`
+- operationId: `post_agent_session_message_agent_sessions__session_id__messages_post` (also callable as `g8.api.call("post_agent_session_message_agent_sessions__session_id__messages_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Append a message to an agent session WITHOUT asking for a reply.
+
+No model runs and nothing is charged: the message is stored in the
+session's log and shown to anyone watching it. Use `POST /agent/chat` to
+get an answer. A session you cannot see is a 404.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.session_id` | `string` | yes | Session id (UUID). |
+| `body` | `AgentSessionMessageRequest` | yes | Request body; fields below. |
+
+Body fields (`AgentSessionMessageRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.content` | `string` | yes | The message text. min length 1, max length 10000 |
+
+**Returns** `ApiResponse_AgentConversationPayload_`: the envelope `{ data: AgentConversationPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.postAgentSessionMessage({ path: { session_id: "id" }, body: { content: "example" } });
+```
+
+---
+
+<a id="op-projectagentdiscovery"></a>
+
+### `g8.api.agents.projectAgentDiscovery(input?)`
+
+**Project Agent Discovery**
+
+- HTTP: `POST /api/v1/agent/onboarding/discovery/project`
+- operationId: `project_agent_discovery_agent_onboarding_discovery_project_post` (also callable as `g8.api.call("project_agent_discovery_agent_onboarding_discovery_project_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Turn the interview into real objects: an ICP, a persona, AND A CAMPAIGN.
+
+Takes no body. The campaign is the part that surprises people, so it is
+said plainly: this CREATES a campaign and provisions its Work channel. It
+does not SEND anything - the campaign sits there for a human to launch -
+which is why this is a `write` and not an `external` operation.
+
+IDEMPOTENT: the projection is idempotent by object name, and the build is
+claim-fenced, so calling twice updates the same ICP and returns the same
+campaign rather than minting a second one.
+
+PARTIAL SUCCESS IS A REAL OUTCOME. A refused build does not fail the
+projection, because the ICP and persona are committed by the time the build
+runs and reporting the whole call as failed would send someone to re-run a
+projection that worked. Read `campaign.ok` in the body; a blocked build
+names what is still open rather than counting it.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OnboardingPayload_`: the envelope `{ data: OnboardingPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.projectAgentDiscovery();
+```
+
+---
+
+<a id="op-putagentoperatingmodel"></a>
+
+### `g8.api.agents.putAgentOperatingModel(input)`
+
+**Put Agent Operating Model**
+
+- HTTP: `PUT /api/v1/agent/operators/operating-model`
+- operationId: `put_agent_operating_model_agent_operators_operating_model_put` (also callable as `g8.api.call("put_agent_operating_model_agent_operators_operating_model_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Replace the organisation's operating-model override. PUT SEMANTICS.
+
+The whole document is replaced: a key absent from `override` is REMOVED,
+not left alone, and an empty object resets the org to graph8's defaults.
+That is the app's behaviour and this does not soften it - a partial-update
+spelling here would make the same body mean two different things on two
+surfaces.
+
+This is a policy document, not a switch, which is why it is tiered `write`
+while `/enabled` is not: it describes the org, and an operator has to be
+turned on separately before anything reads it unattended.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `OperatingModelRequest` | yes | Request body; fields below. |
+
+Body fields (`OperatingModelRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.override` | `Record<string, unknown>` | yes | The organisation's operating-model override, REPLACED WHOLE. This is a PUT: keys absent from the body are removed, not left alone. Read `GET /agent/operators/operating-model` first and send it back modified. |
+
+**Returns** `ApiResponse_OperatorPayload_`: the envelope `{ data: OperatorPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.putAgentOperatingModel({ body: { override: {} } });
+```
+
+---
+
+<a id="op-quoteagentsessionvoice"></a>
+
+### `g8.api.agents.quoteAgentSessionVoice(input)`
+
+**Quote Agent Session Voice**
+
+- HTTP: `POST /api/v1/agent/sessions/{session_id}/voice/quote`
+- operationId: `quote_agent_session_voice_agent_sessions__session_id__voice_quote_post` (also callable as `g8.api.call("quote_agent_session_voice_agent_sessions__session_id__voice_quote_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+What a voice session WOULD cost. Charges nothing.
+
+A POST only because the ceilings are a body. It returns a credit figure and
+a `rate_version`, and that version is the point: hand it straight to
+`POST /agent/sessions/{session_id}/voice`, which refuses a stale one rather
+than starting at today's price against yesterday's quote.
+
+Tiered as a READ for that reason. It is the only way to learn the price
+before committing to it, so a read-only key must be able to call it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.session_id` | `string` | yes | Session id (UUID). |
+| `body` | `VoiceQuoteRequest` | yes | Request body; fields below. |
+
+Body fields (`VoiceQuoteRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.voice_id` | `string (uuid)` | yes | Which voice to price. |
+| `body.max_input_seconds` | `integer` | no | Ceiling on spoken input to price for. default `600`, min 1, max 1200 |
+| `body.max_output_characters` | `integer` | no | Ceiling on synthesised output to price for. default `5000`, min 0, max 60000 |
+
+**Returns** `ApiResponse_AgentSessionStatePayload_`: the envelope `{ data: AgentSessionStatePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.quoteAgentSessionVoice({
+  path: { session_id: "id" },
+  body: { voice_id: "00000000-0000-0000-0000-000000000000" },
+});
+```
+
+---
+
+<a id="op-ratifyagentdiscovery"></a>
+
+### `g8.api.agents.ratifyAgentDiscovery(input)`
+
+**Ratify Agent Discovery**
+
+- HTTP: `POST /api/v1/agent/onboarding/discovery/ratify`
+- operationId: `ratify_agent_discovery_agent_onboarding_discovery_ratify_post` (also callable as `g8.api.call("ratify_agent_discovery_agent_onboarding_discovery_ratify_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Correct what the agent inferred. The customer's word wins over the scrape.
+
+`edits` overrides a value; `confirmed` accepts one as read. Both default to
+empty, so ratifying nothing is a legal no-op rather than a 422 - which is
+what makes the call safe to retry.
+
+The response echoes PROGRESS, not the field list: `fields` comes back empty
+by design because the caller already holds it from `GET /discovery`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DiscoveryRatifyRequest` | yes | Request body; fields below. |
+
+Body fields (`DiscoveryRatifyRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.confirmed` | `Array<string>` | no | Field keys the customer accepts as the agent inferred them. |
+| `body.edits` | `Record<string, unknown>` | no | Field key -> corrected value, for answers the agent got wrong. |
+| `body.session_id` | `string \| null` | no | Canvas session to report the ratification into. |
+
+**Returns** `ApiResponse_OnboardingPayload_`: the envelope `{ data: OnboardingPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.ratifyAgentDiscovery({ body: {} });
+```
+
+---
+
+<a id="op-renameagentsession"></a>
+
+### `g8.api.agents.renameAgentSession(input)`
+
+**Rename Agent Session**
+
+- HTTP: `POST /api/v1/agent/sessions/{session_id}/rename`
+- operationId: `rename_agent_session_agent_sessions__session_id__rename_post` (also callable as `g8.api.call("rename_agent_session_agent_sessions__session_id__rename_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Rename a session. Owner only.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.session_id` | `string` | yes | Session id. |
+| `body` | `AgentSessionRenameRequest` | yes | Request body; fields below. |
+
+Body fields (`AgentSessionRenameRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.title` | `string` | yes | New title. min length 1 |
+
+**Returns** `ApiResponse_AgentSession_`: the envelope `{ data: AgentSession, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentSession` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_at` | `string (date-time) \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `is_pinned` | `boolean \| null` | no |  |
+| `mode` | `string \| null` | no | Session mode, e.g. `general`. |
+| `title` | `string \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.renameAgentSession({ path: { session_id: "id" }, body: { title: "Example" } });
+```
+
+---
+
+<a id="op-requestagentapprovalchanges"></a>
+
+### `g8.api.agents.requestAgentApprovalChanges(input)`
+
+**Request Agent Approval Changes**
+
+- HTTP: `POST /api/v1/agent/approvals/{approval_id}/request-changes`
+- operationId: `request_agent_approval_changes_agent_approvals__approval_id__request_changes_post` (also callable as `g8.api.call("request_agent_approval_changes_agent_approvals__approval_id__request_changes_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Send the agent back to replan, with a reason. THIS REJECTS THE PROPOSAL.
+
+Not a "hold" and not a comment: the current proposal is rejected
+ATOMICALLY, and the feedback is stored alongside so the next plan is
+informed rather than identical. If you want the plan to proceed, use
+`POST /agent/approvals/{approval_id}/decide`.
+
+It FAILS CLOSED on both halves. A deployment that does not have this route
+404s rather than doing something approximate, and a worker that does not
+understand the stored feedback still reads the row as a rejection. There is
+no version of "older software saw this as approval".
+
+Once decided, an approval cannot be decided again - the winner is settled
+server-side, so a second call gets 409 rather than overwriting.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.approval_id` | `string` | yes | Approval id (UUID). |
+| `body` | `ApprovalChangeRequest` | yes | Request body; fields below. |
+
+Body fields (`ApprovalChangeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.feedback` | `string` | yes | Why the proposal is wrong, and what to do instead. REQUIRED and not decoration: it is stored on the rejection and is what the next plan is built from, so an empty-handed rejection produces the same plan again. |
+
+**Returns** `ApiResponse_AgentBenchPayload_`: the envelope `{ data: AgentBenchPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.requestAgentApprovalChanges({ path: { approval_id: "id" }, body: { feedback: "example" } });
+```
+
+---
+
+<a id="op-searchagentmentions"></a>
+
+### `g8.api.agents.searchAgentMentions(input)`
+
+**Search Agent Mentions**
+
+- HTTP: `POST /api/v1/agent/mention-search`
+- operationId: `search_agent_mentions_agent_mention_search_post` (also callable as `g8.api.call("search_agent_mentions_agent_mention_search_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `workflows:read`
+
+Resolve an @-mention: what can be referred to in a message to the agent.
+
+Searches people, campaigns, accounts and documents in one call and returns
+them with a `category`, so a composer can render one picker instead of four.
+A read - it finds things, it changes nothing, and it starts no agent.
+
+A POST only because the filter set is a body. `query` defaults to empty,
+which returns the default suggestions rather than nothing, matching the app.
+
+The app publishes the SAME search at `/v1/copilot/mention-search` from a
+second router that lazily imports this one's helpers. One is enough on a
+versioned contract, and this is the one under `/agent`, beside the sessions
+the mentions are typed into.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `MentionSearchRequest` | yes | Request body; fields below. |
+
+Body fields (`MentionSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.campaign_id` | `string \| null` | no | Bias results toward one campaign's people and documents. |
+| `body.mode` | `string \| null` | no | Which mention vocabulary to search. Left open rather than closed to a Literal: the app treats an unrecognised mode as 'no filter' instead of an error, so closing it here would turn a working call into a 422. |
+| `body.query` | `string` | no | Substring to match. Empty - the default - returns the default suggestions rather than nothing, matching the app's own composer. default `""` |
+
+**Returns** `ApiResponse_AgentBenchListPayload_`: the envelope `{ data: AgentBenchListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentBenchListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.searchAgentMentions({ body: {} });
+```
+
+---
+
+<a id="op-setagentoperatorenabled"></a>
+
+### `g8.api.agents.setAgentOperatorEnabled(input)`
+
+**Set Agent Operator Enabled**
+
+- HTTP: `PUT /api/v1/agent/operators/{operator}/enabled`
+- operationId: `set_agent_operator_enabled_agent_operators__operator__enabled_put` (also callable as `g8.api.call("set_agent_operator_enabled_agent_operators__operator__enabled_put", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `workflows:run`
+
+Switch this operator on or off for the organisation.
+
+TURNING IT ON STARTS UNATTENDED WORK. The operator's monitors begin running
+on their own schedule, without anyone asking, and they keep running until
+this is set back to false. That is why this needs the `run` grant rather
+than plain write: "let something act in my org when I am not watching" is
+not the same permission as "edit a record".
+
+What it is allowed to DO once it is on is a separate control - see
+`PUT /agent/operators/{operator}/skills/{skill_key}`. Enabling an operator
+whose skills are all `OFF` starts nothing.
+
+`enabled` is explicit rather than a toggle, so a retried request is
+idempotent instead of switching it back off.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+| `body` | `OperatorEnabledRequest` | yes | Request body; fields below. |
+
+Body fields (`OperatorEnabledRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.enabled` | `boolean` | yes | Whether this operator runs for the organisation. TURNING IT ON STARTS UNATTENDED WORK: the operator's monitors run on their own schedule from then on, without a person asking. Explicit rather than a toggle, so a retried request is idempotent instead of flipping the state back. |
+
+**Returns** `ApiResponse_OperatorPayload_`: the envelope `{ data: OperatorPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.agents.setAgentOperatorEnabled({ path: { operator: "example" }, body: { enabled: true } });
+```
+
+---
+
+<a id="op-setagentoperatorrecipient"></a>
+
+### `g8.api.agents.setAgentOperatorRecipient(input)`
+
+**Set Agent Operator Recipient**
+
+- HTTP: `PUT /api/v1/agent/operators/{operator}/recipient`
+- operationId: `set_agent_operator_recipient_agent_operators__operator__recipient_put` (also callable as `g8.api.call("set_agent_operator_recipient_agent_operators__operator__recipient_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Name the person who owns this operator's approvals.
+
+REPLACES the current recipient - there is one per operator, not a list.
+Worth setting before enabling anything at `PROPOSE`, because an approval
+task with no owner is an operator that has stopped.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+| `body` | `OperatorRecipientRequest` | yes | Request body; fields below. |
+
+Body fields (`OperatorRecipientRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.user_id` | `string` | yes | The person who receives this operator's alerts and owns its approval tasks. One recipient per operator: setting it REPLACES whoever was there. |
+
+**Returns** `ApiResponse_OperatorPayload_`: the envelope `{ data: OperatorPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.setAgentOperatorRecipient({ path: { operator: "example" }, body: { user_id: "id" } });
+```
+
+---
+
+<a id="op-setagentoperatortrustdial"></a>
+
+### `g8.api.agents.setAgentOperatorTrustDial(input)`
+
+**Set Agent Operator Trust Dial**
+
+- HTTP: `PUT /api/v1/agent/operators/{operator}/skills/{skill_key}`
+- operationId: `set_agent_operator_trust_dial_agent_operators__operator__skills__skill_key__put` (also callable as `g8.api.call("set_agent_operator_trust_dial_agent_operators__operator__skills__skill_key__put", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `workflows:run`
+
+Set how far ONE skill may go on its own. THIS GOVERNS UNATTENDED ACTION.
+
+The trust dial is the control that decides whether a finding stays a
+finding, becomes an approval a person decides, or is simply DONE. Raising
+it is the single most consequential write on this surface, which is why it
+takes the `run` grant rather than plain write.
+
+THE DIAL IS A CEILING REQUEST, NOT A SETTING. The effective autonomy is the
+minimum of this value, the skill's graph8-managed risk cap and the platform
+ceiling, so a skill capped at `PROPOSE` stays at `PROPOSE` no matter what
+is sent. Read the response rather than assuming the write took literally.
+
+Read `GET /agent/operators/{operator}/scorecard` first. A dial raised on a
+skill that has been wrong is how unattended work becomes unattended damage.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.operator` | `string` | yes |  |
+| `path.skill_key` | `string` | yes | Skill key from `GET /agent/operators/{operator}/skills`. |
+| `body` | `OperatorTrustDialRequest` | yes | Request body; fields below. |
+
+Body fields (`OperatorTrustDialRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.autonomy` | `"OFF" \| "DETECT" \| "PROPOSE" \| "AUTO"` | yes | How far this skill may go on its own. `OFF` - do not run it. `DETECT` - look, and record what it finds. `PROPOSE` - look, and raise an approval task a person decides. `AUTO` - act and log, with no human in the loop. THIS IS A REQUEST, NOT A GUARANTEE: the effective level is the MINIMUM of this dial, the skill's own graph8-managed risk cap and the platform ceiling, so a skill capped at `PROPOSE` s… |
+
+**Returns** `ApiResponse_OperatorPayload_`: the envelope `{ data: OperatorPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.agents.setAgentOperatorTrustDial({
+  path: { operator: "example", skill_key: "example" },
+  body: { autonomy: "OFF" },
+});
+```
+
+---
+
+<a id="op-setupagentdiscoverysignals"></a>
+
+### `g8.api.agents.setupAgentDiscoverySignals(input?)`
+
+**Setup Agent Discovery Signals**
+
+- HTTP: `POST /api/v1/agent/onboarding/discovery/signals`
+- operationId: `setup_agent_discovery_signals_agent_onboarding_discovery_signals_post` (also callable as `g8.api.call("setup_agent_discovery_signals_agent_onboarding_discovery_signals_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Create the global custom column behind each observable trigger.
+
+Takes no body. A signal is defined ONCE for the account and every list
+patches the same column - that is what makes cross-campaign analysis
+possible at all, and why the column is global rather than list-scoped.
+
+Triggers nothing can observe come back as `research` rather than being
+quietly created: they are real and useful, but they belong in the copy
+rather than in the targeting. Promising to watch something nothing watches
+is a program that never fires and a failure nobody can see.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OnboardingPayload_`: the envelope `{ data: OnboardingPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.setupAgentDiscoverySignals();
+```
+
+---
+
+<a id="op-startagentsessionvoice"></a>
+
+### `g8.api.agents.startAgentSessionVoice(input)`
+
+**Start Agent Session Voice**
+
+- HTTP: `POST /api/v1/agent/sessions/{session_id}/voice`
+- operationId: `start_agent_session_voice_agent_sessions__session_id__voice_post` (also callable as `g8.api.call("start_agent_session_voice_agent_sessions__session_id__voice_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `workflows:run`
+
+Start speaking with the agent. THIS SPENDS CREDITS AS IT RUNS.
+
+A live metered session: it begins charging when it connects and keeps
+charging until it is ended or hits `max_credits`. Quote it first.
+
+`max_credits` is a HARD CEILING and is required - there is no default,
+because choosing one would mean this contract picking a spending limit on
+the customer's behalf. `rate_version` must be the one the quote returned.
+
+End it with `DELETE /agent/sessions/{session_id}/voice/{voice_id}`. A
+session left open keeps costing money.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.session_id` | `string` | yes | Session id (UUID). |
+| `body` | `VoiceSessionRequest` | yes | Request body; fields below. |
+
+Body fields (`VoiceSessionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.max_credits` | `integer` | yes | HARD CEILING on what this session may spend. Required, with no default: an uncapped voice session is an open-ended charge, and a contract that defaults it would be choosing a spending limit on the customer's behalf. min 1, max 9223372036854776000 |
+| `body.rate_version` | `string` | yes | The rate version the quote was issued against, from `POST /agent/sessions/{session_id}/voice/quote`. The server refuses a stale one rather than charging today's price for yesterday's quote. min length 1, max length 128 |
+| `body.voice_id` | `string (uuid)` | yes | Which voice to speak with. |
+
+**Returns** `ApiResponse_AgentSessionStatePayload_`: the envelope `{ data: AgentSessionStatePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.agents.startAgentSessionVoice({
+  path: { session_id: "id" },
+  body: {
+    max_credits: 1,
+    rate_version: "example",
+    voice_id: "00000000-0000-0000-0000-000000000000",
+  },
+});
+```
+
+---
+
+<a id="op-steeragentworkitem"></a>
+
+### `g8.api.agents.steerAgentWorkItem(input)`
+
+**Steer Agent Work Item**
+
+- HTTP: `POST /api/v1/agent/work-items/{work_item_id}/steer`
+- operationId: `steer_agent_work_item_agent_work_items__work_item_id__steer_post` (also callable as `g8.api.call("steer_agent_work_item_agent_work_items__work_item_id__steer_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Redirect a RUNNING work item at its next safe step boundary.
+
+Not mid-step - that is what makes steering safe at all. The instruction is
+picked up when the agent reaches a boundary, so a steer sent during a long
+tool call lands afterwards rather than corrupting it.
+
+SAFE TO RETRY: `client_turn_id` is a caller-generated idempotency key, and
+the same id twice comes back `status: "duplicate"` rather than queueing a
+second instruction into a running agent. Check that field before assuming
+a retry did something.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.work_item_id` | `string` | yes | Work item id (UUID). |
+| `body` | `AgentWorkItemSteerRequest` | yes | Request body; fields below. |
+
+Body fields (`AgentWorkItemSteerRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.client_turn_id` | `string (uuid)` | yes | Caller-generated idempotency key. REQUIRED, and the reason steering is safe to retry: the same id twice comes back `duplicate` rather than queueing a second instruction into a running agent. |
+| `body.instruction` | `string` | yes | What to do differently. Applied at the next safe step boundary, not mid-step. min length 1, max length 2000 |
+
+**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.agents.steerAgentWorkItem({
+  path: { work_item_id: "id" },
+  body: {
+    client_turn_id: "00000000-0000-0000-0000-000000000000",
+    instruction: "example",
+  },
+});
+```
+
+---
+
+<a id="op-submitagentdomainresponse"></a>
+
+### `g8.api.agents.submitAgentDomainResponse(input)`
+
+**Submit Agent Domain Response**
+
+- HTTP: `POST /api/v1/agent/onboarding/domain-response`
+- operationId: `submit_agent_domain_response_agent_onboarding_domain_response_post` (also callable as `g8.api.call("submit_agent_domain_response_agent_onboarding_domain_response_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Answer the agent's "is this your company domain?" card.
+
+`domain` is REQUIRED when `confirmed` is false and ignored when it is true.
+The app enforces that with a 422 of its own, and this mirrors the model
+rather than the check, so a missing domain is refused by the handler with
+its own message rather than by a copy here that could drift.
+
+A corrected domain is persisted immediately, so a late edit is not orphaned
+once the polling activity has already exited.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DomainConfirmationRequest` | yes | Request body; fields below. |
+
+Body fields (`DomainConfirmationRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.card_id` | `string` | yes | The `domain_confirmation` card id. |
+| `body.confirmed` | `boolean` | yes | True = the pre-filled domain is correct as it stands. |
+| `body.session_id` | `string` | yes | The proactive-setup canvas session id. |
+| `body.domain` | `string \| null` | no | The corrected company domain. REQUIRED when `confirmed` is false; ignored when it is true. |
+
+**Returns** `ApiResponse_OnboardingPayload_`: the envelope `{ data: OnboardingPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.agents.submitAgentDomainResponse({ body: { card_id: "id", confirmed: true, session_id: "id" } });
+```
+
+---
+
+<a id="op-takeagentdiscoveryturn"></a>
+
+### `g8.api.agents.takeAgentDiscoveryTurn(input)`
+
+**Take Agent Discovery Turn**
+
+- HTTP: `POST /api/v1/agent/onboarding/discovery/turn`
+- operationId: `take_agent_discovery_turn_agent_onboarding_discovery_turn_post` (also callable as `g8.api.call("take_agent_discovery_turn_agent_onboarding_discovery_turn_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `workflows:run`
+
+One conversational turn of the kickoff. THIS ONE COSTS MONEY.
+
+The only route on this surface that makes an LLM call, which is why it is
+tiered `billable` and why the app rate-limits it at 20 requests a minute
+per organisation - far above a human conversation, far below anything that
+shows up on a bill. Over that, the app answers 429 with `Retry-After`.
+
+The model replies AND states what it learned in one forced tool call, so a
+message that answers four questions records four fields. Everything it
+claims is validated before it is written: a key outside the framework is
+dropped, and a `green` with no supporting quote is DOWNGRADED to `amber`
+rather than trusted.
+
+The turn writes only to the discovery record. It provisions nothing, calls
+no tools, and sends nothing.
+
+There is no `history` parameter and that is deliberate - see the module
+docstring.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DiscoveryTurnRequest` | yes | Request body; fields below. |
+
+Body fields (`DiscoveryTurnRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.message` | `string` | yes | min length 1, max length 8000 |
+| `body.session_id` | `string \| null` | no | Canvas session to report into. |
+
+**Returns** `ApiResponse_OnboardingPayload_`: the envelope `{ data: OnboardingPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.agents.takeAgentDiscoveryTurn({ body: { message: "example" } });
+```
+
+---
+
+<a id="op-updateagentsession"></a>
+
+### `g8.api.agents.updateAgentSession(input)`
+
+**Update Agent Session**
+
+- HTTP: `PATCH /api/v1/agent/sessions/{session_id}`
+- operationId: `update_agent_session_agent_sessions__session_id__patch` (also callable as `g8.api.call("update_agent_session_agent_sessions__session_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `workflows:write`
+
+Append messages or change the title. Omitted fields are untouched.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.session_id` | `string` | yes | Session id. |
+| `body` | `AgentSessionUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`AgentSessionUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.messages` | `Array<Record<string, unknown>> \| null` | no |  |
+| `body.title` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_AgentSession_`: the envelope `{ data: AgentSession, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AgentSession` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_at` | `string (date-time) \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `is_pinned` | `boolean \| null` | no |  |
+| `mode` | `string \| null` | no | Session mode, e.g. `general`. |
+| `title` | `string \| null` | no |  |
+| `updated_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.agents.updateAgentSession({ path: { session_id: "id" }, body: {} });
+```