@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/gtmContext.md

@@ -0,0 +1,2112 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.gtmContext`: GTM Context
+
+51 operations (17 read, 23 write, 6 destructive, 5 billable).
+
+13 of these also have a hand-written method (`g8.mailboxes`, `g8.studio`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [gtmContext.d.ts](gtmContext.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`approveCompanyProfile`](#op-approvecompanyprofile) | `POST /api/v1/company-profile/approve` | write | `campaigns:write` | Approve Company Profile |
+| [`approveCompanyProfileKeywords`](#op-approvecompanyprofilekeywords) | `POST /api/v1/company-profile/keywords/approve` | write | `campaigns:write` | Approve Company Profile Keywords |
+| [`archiveIcp`](#op-archiveicp) ★ | `POST /api/v1/icps/{icp_id}/archive` | destructive | `campaigns:delete` | Archive Icp |
+| [`archivePersona`](#op-archivepersona) ★ | `POST /api/v1/personas/{persona_id}/archive` | destructive | `campaigns:delete` | Archive Persona |
+| [`createIcp`](#op-createicp) ★ | `POST /api/v1/icps` | write | `campaigns:write` | Create Icp |
+| [`createPersona`](#op-createpersona) ★ | `POST /api/v1/personas` | write | `campaigns:write` | Create Persona |
+| [`deleteAllDocuments`](#op-deletealldocuments) | `DELETE /api/v1/global-context/documents` | destructive | `campaigns:delete` | Delete All Documents |
+| [`deleteDocument`](#op-deletedocument) | `DELETE /api/v1/global-context/documents/{doc_type}` | destructive | `campaigns:delete` | Delete Document |
+| [`extractCompanyData`](#op-extractcompanydata) | `POST /api/v1/global-context/extract-company-data` | write | `campaigns:write` | Extract Company Data |
+| [`generateAllDocuments`](#op-generatealldocuments) | `POST /api/v1/global-context/generate-all` | billable | `campaigns:run` | Generate All Documents |
+| [`generateCompanyProfile`](#op-generatecompanyprofile) | `POST /api/v1/company-profile/generate` | billable | `campaigns:run` | Generate Company Profile |
+| [`getBuyingJourneyCrmStatus`](#op-getbuyingjourneycrmstatus) | `GET /api/v1/global-context/documents/buying-journey/crm-status` | read | `campaigns:read` | Get Buying Journey Crm Status |
+| [`getCompanyProfile`](#op-getcompanyprofile) | `GET /api/v1/company-profile` | read | `campaigns:read` | Get Company Profile |
+| [`getCompanyProfileWorkflowStatus`](#op-getcompanyprofileworkflowstatus) | `GET /api/v1/company-profile/workflow-status` | read | `campaigns:read` | Get Company Profile Workflow Status |
+| [`getDocHighlights`](#op-getdochighlights) | `GET /api/v1/global-context/doc/{doc_type}/highlights` | read | `campaigns:read` | Get Doc Highlights |
+| [`getDocumentsAnalytics`](#op-getdocumentsanalytics) | `GET /api/v1/global-context/documents/analytics` | read | `campaigns:read` | Get Documents Analytics |
+| [`getGlobalContextDocument`](#op-getglobalcontextdocument) | `GET /api/v1/global-context/documents/{doc_id}` | read | `campaigns:read` | Get Global Context Document |
+| [`getLatestPipeline`](#op-getlatestpipeline) | `GET /api/v1/global-context/pipeline/latest` | read | `campaigns:read` | Get Latest Pipeline |
+| [`getMailboxWarmupAnalytics`](#op-getmailboxwarmupanalytics) ★ | `GET /api/v1/mailboxes/{mailbox_id}/warmup` | read | `campaigns:read` | Get Mailbox Warmup Analytics |
+| [`getPipelineStatus`](#op-getpipelinestatus) | `GET /api/v1/global-context/pipeline/{pipeline_id}` | read | `campaigns:read` | Get Pipeline Status |
+| [`listActivities`](#op-listactivities) | `GET /api/v1/activities` | read | `campaigns:read` | List Activities |
+| [`listGlobalContextDocuments`](#op-listglobalcontextdocuments) ★ | `GET /api/v1/global-context/documents` | read | `campaigns:read` | List Global Context Documents |
+| [`listIcps`](#op-listicps) ★ | `GET /api/v1/icps` | read | `campaigns:read` | List Icps |
+| [`listIntelligenceData`](#op-listintelligencedata) ★ | `GET /api/v1/intelligence-data` | read | `campaigns:read` | List Intelligence Data |
+| [`listMailboxes`](#op-listmailboxes) ★ | `GET /api/v1/mailboxes` | read | `campaigns:read` | List Mailboxes |
+| [`listPersonas`](#op-listpersonas) ★ | `GET /api/v1/personas` | read | `campaigns:read` | List Personas |
+| [`listPipelines`](#op-listpipelines) | `GET /api/v1/global-context/pipelines` | read | `campaigns:read` | List Pipelines |
+| [`listResearchReports`](#op-listresearchreports) ★ | `GET /api/v1/research-reports` | read | `campaigns:read` | List Research Reports |
+| [`regenerateGlobalContext`](#op-regenerateglobalcontext) | `POST /api/v1/global-context/regenerate` | write | `campaigns:write` | Regenerate Global Context |
+| [`regenerateOneDocument`](#op-regenerateonedocument) | `POST /api/v1/global-context/{doc_id}/regenerate` | write | `campaigns:write` | Regenerate One Document |
+| [`reindexAllDocuments`](#op-reindexalldocuments) | `POST /api/v1/global-context/reindex-all` | write | `campaigns:write` | Reindex All Documents |
+| [`reindexCompanyProfile`](#op-reindexcompanyprofile) | `POST /api/v1/company-profile/reindex` | billable | `campaigns:run` | Reindex Company Profile |
+| [`resetCompanyProfileKeywords`](#op-resetcompanyprofilekeywords) | `DELETE /api/v1/company-profile/keywords` | destructive | `campaigns:delete` | Reset Company Profile Keywords |
+| [`resetStuckDocuments`](#op-resetstuckdocuments) | `POST /api/v1/global-context/reset-stuck-documents` | destructive | `campaigns:delete` | Reset Stuck Documents |
+| [`resumePipeline`](#op-resumepipeline) | `POST /api/v1/global-context/resume-pipeline` | write | `campaigns:write` | Resume Pipeline |
+| [`retryCompanyProfile`](#op-retrycompanyprofile) | `POST /api/v1/company-profile/retry` | billable | `campaigns:run` | Retry Company Profile |
+| [`saveBuyingJourneyInterview`](#op-savebuyingjourneyinterview) | `POST /api/v1/global-context/documents/buying-journey/interview` | write | `campaigns:write` | Save Buying Journey Interview |
+| [`scaffoldAllDocuments`](#op-scaffoldalldocuments) | `POST /api/v1/global-context/scaffold` | write | `campaigns:write` | Scaffold All Documents |
+| [`scaffoldCompanyKeywords`](#op-scaffoldcompanykeywords) | `POST /api/v1/global-context/scaffold-company-keywords` | write | `campaigns:write` | Scaffold Company Keywords |
+| [`scaffoldCompanyProfile`](#op-scaffoldcompanyprofile) | `POST /api/v1/global-context/scaffold-company-profile` | write | `campaigns:write` | Scaffold Company Profile |
+| [`stopAllGeneration`](#op-stopallgeneration) | `POST /api/v1/global-context/stop-all-generation` | write | `campaigns:write` | Stop All Generation |
+| [`submitDocumentFeedback`](#op-submitdocumentfeedback) | `POST /api/v1/global-context/documents/{doc_id}/feedback` | write | `campaigns:write` | Submit Document Feedback |
+| [`trackDocumentUsage`](#op-trackdocumentusage) | `POST /api/v1/global-context/documents/{doc_id}/track-usage` | write | `campaigns:write` | Track Document Usage |
+| [`unapproveCompanyProfile`](#op-unapprovecompanyprofile) | `POST /api/v1/company-profile/unapprove` | write | `campaigns:write` | Unapprove Company Profile |
+| [`updateCompanyProfile`](#op-updatecompanyprofile) | `PUT /api/v1/company-profile` | write | `campaigns:write` | Update Company Profile |
+| [`updateGlobalContextDocument`](#op-updateglobalcontextdocument) | `PATCH /api/v1/global-context/documents/{doc_id}` | write | `campaigns:write` | Update Global Context Document |
+| [`updateIcp`](#op-updateicp) ★ | `PATCH /api/v1/icps/{icp_id}` | write | `campaigns:write` | Update Icp |
+| [`updatePersona`](#op-updatepersona) ★ | `PATCH /api/v1/personas/{persona_id}` | write | `campaigns:write` | Update Persona |
+| [`updateResearchReport`](#op-updateresearchreport) | `PATCH /api/v1/research-reports/{report_id}` | billable | `campaigns:run` | Update Research Report |
+| [`uploadCompanyProfileLogo`](#op-uploadcompanyprofilelogo) | `POST /api/v1/company-profile/logo` | write | `campaigns:write` | Upload Company Profile Logo |
+| [`uploadEnablementAsset`](#op-uploadenablementasset) | `POST /api/v1/enablement/assets` | write | `campaigns:write` | Upload Enablement Asset |
+
+---
+
+<a id="op-approvecompanyprofile"></a>
+
+### `g8.api.gtmContext.approveCompanyProfile(input)`
+
+**Approve Company Profile**
+
+- HTTP: `POST /api/v1/company-profile/approve`
+- operationId: `approve_company_profile_company_profile_approve_post` (also callable as `g8.api.call("approve_company_profile_company_profile_approve_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Approve the profile. It becomes the org's source of truth and is locked.
+
+Refused until the first generation run has completed. Undo with
+`POST /company-profile/unapprove`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ProfileWebsiteRequest` | yes | Request body; fields below. |
+
+Body fields (`ProfileWebsiteRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.website_url` | `string` | yes | Website the profile was built from. Matched on its canonical domain. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.approveCompanyProfile({ body: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-approvecompanyprofilekeywords"></a>
+
+### `g8.api.gtmContext.approveCompanyProfileKeywords(input)`
+
+**Approve Company Profile Keywords**
+
+- HTTP: `POST /api/v1/company-profile/keywords/approve`
+- operationId: `approve_company_profile_keywords_company_profile_keywords_approve_post` (also callable as `g8.api.call("approve_company_profile_keywords_company_profile_keywords_approve_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Approve the profile's keyword set. 404 until a profile with keywords exists.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ProfileWebsiteRequest` | yes | Request body; fields below. |
+
+Body fields (`ProfileWebsiteRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.website_url` | `string` | yes | Website the profile was built from. Matched on its canonical domain. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.approveCompanyProfileKeywords({ body: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-archiveicp"></a>
+
+### `g8.api.gtmContext.archiveIcp(input)`
+
+**Archive Icp**
+
+- HTTP: `POST /api/v1/icps/{icp_id}/archive`
+- operationId: `archive_icp_icps__icp_id__archive_post` (also callable as `g8.api.call("archive_icp_icps__icp_id__archive_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+- ★ Hand-written: [`g8.studio.archiveIcp()`](../sdk-clients.md#g8-studio-archiveicp)
+
+Archive a Studio ICP (soft delete - sets status='archived').
+
+Archived ICPs drop out of the default ``GET /icps`` listing but remain fetchable
+via ``?status=archived``. Returns 404 if the ICP does not exist.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.icp_id` | `string` | yes | ICP 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.gtmContext.archiveIcp({ path: { icp_id: "id" } });
+```
+
+---
+
+<a id="op-archivepersona"></a>
+
+### `g8.api.gtmContext.archivePersona(input)`
+
+**Archive Persona**
+
+- HTTP: `POST /api/v1/personas/{persona_id}/archive`
+- operationId: `archive_persona_personas__persona_id__archive_post` (also callable as `g8.api.call("archive_persona_personas__persona_id__archive_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+- ★ Hand-written: [`g8.studio.archivePersona()`](../sdk-clients.md#g8-studio-archivepersona)
+
+Archive a Studio persona (soft delete - sets status='archived').
+
+Archived personas drop out of the default ``GET /personas`` listing but remain
+fetchable via ``?status=archived``. Returns 404 if the persona does not exist.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.persona_id` | `string` | yes | Persona 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.gtmContext.archivePersona({ path: { persona_id: "id" } });
+```
+
+---
+
+<a id="op-createicp"></a>
+
+### `g8.api.gtmContext.createIcp(input)`
+
+**Create Icp**
+
+- HTTP: `POST /api/v1/icps`
+- operationId: `create_icp_icps_post` (also callable as `g8.api.call("create_icp_icps_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+- ★ Hand-written: [`g8.studio.createIcp()`](../sdk-clients.md#g8-studio-createicp)
+
+Create a Studio ICP (manual - no AI generation).
+
+Read-side counterpart already exists (``GET /icps``); this closes the
+"read but can't create" gap for the ICP bucket. The new ICP is created with
+status 'active' and returned in the same shape as ``GET /icps``.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CreateIcpRequest` | yes | Request body; fields below. |
+
+Body fields (`CreateIcpRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes | ICP name/title. |
+| `body.website_url` | `string` | yes | The org website this ICP belongs to. |
+| `body.buying_signals` | `Array<unknown> \| null` | no | List of buying-intent signals. |
+| `body.description` | `string \| null` | no | Freeform ICP description. |
+| `body.estimated_market_size` | `integer \| null` | no | Estimated addressable-market count. |
+| `body.firmographics` | `Record<string, unknown> \| null` | no | Firmographic criteria (industry, size, geo, ...). |
+| `body.tech_stack` | `Record<string, unknown> \| null` | no | Technology signals. |
+
+**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.gtmContext.createIcp({ body: { name: "Example", website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-createpersona"></a>
+
+### `g8.api.gtmContext.createPersona(input)`
+
+**Create Persona**
+
+- HTTP: `POST /api/v1/personas`
+- operationId: `create_persona_personas_post` (also callable as `g8.api.call("create_persona_personas_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+- ★ Hand-written: [`g8.studio.createPersona()`](../sdk-clients.md#g8-studio-createpersona)
+
+Create a Studio buyer persona (manual - no AI generation).
+
+Read-side counterpart already exists (``GET /personas``); this closes the
+"read but can't create" gap for the Persona bucket. The new persona is created
+with status 'active' and returned in the same shape as ``GET /personas``.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CreatePersonaRequest` | yes | Request body; fields below. |
+
+Body fields (`CreatePersonaRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.title` | `string` | yes | Persona title (e.g. 'Director of Marketing Operations'). |
+| `body.website_url` | `string` | yes | The org website this persona belongs to. |
+| `body.campaign_approach` | `string \| null` | no | Recommended campaign approach. |
+| `body.confidence` | `string \| null` | no | Confidence label (e.g. 'high'/'medium'/'low'). Defaults to 'medium'. |
+| `body.expected_receptivity` | `string \| null` | no | Expected receptivity note. |
+| `body.key_signals` | `Array<unknown> \| null` | no | List of buying/intent signals. |
+| `body.priority` | `integer \| null` | no | Display priority (lower sorts first). Defaults to 1. |
+| `body.recommended_goal` | `string \| null` | no | Recommended campaign goal. |
+| `body.source` | `string \| null` | no | Origin label for the persona. Defaults to 'manual'. |
+| `body.why_target` | `string \| null` | no | Why this persona is worth targeting. |
+
+**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.gtmContext.createPersona({ body: { title: "Example", website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-deletealldocuments"></a>
+
+### `g8.api.gtmContext.deleteAllDocuments(input?)`
+
+**Delete All Documents**
+
+- HTTP: `DELETE /api/v1/global-context/documents`
+- operationId: `delete_all_documents_global_context_documents_delete` (also callable as `g8.api.call("delete_all_documents_global_context_documents_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Delete EVERY Global Context document for this organisation.
+
+NOT REVERSIBLE, and it is the whole library: every ICP, persona, buying
+journey and profile the org has. Everything downstream that grounds on them
+- campaign generation, the copilot, retrieval - is generating from nothing
+until they are rebuilt.
+
+The narrower operation is `DELETE /global-context/documents/{doc_type}`.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `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.gtmContext.deleteAllDocuments();
+```
+
+---
+
+<a id="op-deletedocument"></a>
+
+### `g8.api.gtmContext.deleteDocument(input)`
+
+**Delete Document**
+
+- HTTP: `DELETE /api/v1/global-context/documents/{doc_type}`
+- operationId: `delete_document_global_context_documents__doc_type__delete` (also callable as `g8.api.call("delete_document_global_context_documents__doc_type__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Delete ONE document, by TYPE rather than by id.
+
+The path parameter is a type key, not a document id - deleting
+`company_profile` removes whichever document currently holds that type.
+Not reversible.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_type` | `string` | yes | Document type key, e.g. `company_profile`, `icp_research`, `buying_journey`. Free-form on purpose: the set grows with the product and a closed list here would 422 a document the org already has. |
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `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.gtmContext.deleteDocument({ path: { doc_type: "example" } });
+```
+
+---
+
+<a id="op-extractcompanydata"></a>
+
+### `g8.api.gtmContext.extractCompanyData(input)`
+
+**Extract Company Data**
+
+- HTTP: `POST /api/v1/global-context/extract-company-data`
+- operationId: `extract_company_data_global_context_extract_company_data_post` (also callable as `g8.api.call("extract_company_data_global_context_extract_company_data_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Pull company facts out of scraped intelligence data.
+
+SPENDS CREDITS when `enrich` is true (the default): the route is
+credit-gated before the model call and answers 402 when the balance is
+short. Send `enrich=false` for the scrape-derived fields alone, which costs
+nothing extra.
+
+The app takes an untyped body here; this contract types it, so a missing
+`website_url` is a 422 naming the field rather than a 400 describing it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ExtractCompanyDataRequest` | yes | Request body; fields below. |
+
+Body fields (`ExtractCompanyDataRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.website_url` | `string` | yes | Company website to extract from. Intelligence data for it must already exist. min length 1 |
+| `body.enrich` | `boolean` | no | Enrich the extracted fields through Apollo. SPENDS CREDITS - the call is credit-gated and answers 402 when the balance is short. default `true` |
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.extractCompanyData({ body: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-generatealldocuments"></a>
+
+### `g8.api.gtmContext.generateAllDocuments(input)`
+
+**Generate All Documents**
+
+- HTTP: `POST /api/v1/global-context/generate-all`
+- operationId: `generate_all_documents_global_context_generate_all_post` (also callable as `g8.api.call("generate_all_documents_global_context_generate_all_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Generate the whole Global Context set, in dependency order.
+
+ONE-SHOT. The app refuses this with a 409 once a pipeline has completed for
+the organisation - it is the onboarding path, not a rebuild. To rebuild
+documents that already exist use `POST /global-context/regenerate`.
+
+Requires intelligence data for `website_url` to exist already; without it
+the documents would be generated from nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `GenerateAllDocumentsRequest` | yes | Request body; fields below. |
+
+Body fields (`GenerateAllDocumentsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.website_url` | `string` | yes | The company website every document is generated against. Intelligence data must already exist for it. |
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `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.gtmContext.generateAllDocuments({ body: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-generatecompanyprofile"></a>
+
+### `g8.api.gtmContext.generateCompanyProfile(input)`
+
+**Generate Company Profile**
+
+- HTTP: `POST /api/v1/company-profile/generate`
+- operationId: `generate_company_profile_company_profile_generate_post` (also callable as `g8.api.call("generate_company_profile_company_profile_generate_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+(Re)build the profile's company data from the crawled site. SPENDS CREDITS.
+
+Model calls plus a web-search enrichment; refused with 402 before any
+call when the org is out of credits. REPLACES the unapproved profile data.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ProfileFieldsRequest` | yes | Request body; fields below. |
+
+Body fields (`ProfileFieldsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.fields` | `Record<string, unknown>` | yes | Which profile fields to generate, and their seeds. |
+| `body.website_url` | `string` | yes | The org's website - the profile's key. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.gtmContext.generateCompanyProfile({ body: { fields: {}, website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-getbuyingjourneycrmstatus"></a>
+
+### `g8.api.gtmContext.getBuyingJourneyCrmStatus(input?)`
+
+**Get Buying Journey Crm Status**
+
+- HTTP: `GET /api/v1/global-context/documents/buying-journey/crm-status`
+- operationId: `get_buying_journey_crm_status_global_context_documents_buying_journey_crm_status_get` (also callable as `g8.api.call("get_buying_journey_crm_status_global_context_documents_buying_journey_crm_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Whether there is enough CRM data to ground the buying journey.
+
+The buying journey document is only as good as the closed-won deals behind
+it. This says whether a CRM is connected and how many deals it can see, so
+a caller can find out BEFORE generating a document built on nothing.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.getBuyingJourneyCrmStatus();
+```
+
+---
+
+<a id="op-getcompanyprofile"></a>
+
+### `g8.api.gtmContext.getCompanyProfile(input?)`
+
+**Get Company Profile**
+
+- HTTP: `GET /api/v1/company-profile`
+- operationId: `get_company_profile_company_profile_get` (also callable as `g8.api.call("get_company_profile_company_profile_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Read this org's company profile — the source Studio generation reads from.
+
+Returns the most recently updated profile (``_ordered_profile_candidates``
+orders by ``updated_at`` desc, then ``created_at`` desc, then ``id`` desc, and
+this takes the first row). It does NOT filter by a confirmed domain, so after a
+domain change the row you get back is whichever profile was touched last — call
+``PUT /company-profile`` to set the correct one if the latest is stale.
+
+**Input**: none.
+
+**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.gtmContext.getCompanyProfile();
+```
+
+---
+
+<a id="op-getcompanyprofileworkflowstatus"></a>
+
+### `g8.api.gtmContext.getCompanyProfileWorkflowStatus(input)`
+
+**Get Company Profile Workflow Status**
+
+- HTTP: `GET /api/v1/company-profile/workflow-status`
+- operationId: `get_company_profile_workflow_status_company_profile_workflow_status_get` (also callable as `g8.api.call("get_company_profile_workflow_status_company_profile_workflow_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+How far the profile-building pipeline has got, card by card.
+
+Four stages - intelligence gathering, the merge, approval, and the profile
+itself - each with its own state, so a caller can tell "still crawling"
+from "waiting for a human" from "done".
+
+The `website_url` echoed back is the string you sent; the lookup itself is
+done against its canonical domain, so a match on a differently-spelled URL
+is expected rather than a mismatch.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.website_url` | `string` | yes | The website the profile was built from. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.getCompanyProfileWorkflowStatus({ query: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-getdochighlights"></a>
+
+### `g8.api.gtmContext.getDocHighlights(input)`
+
+**Get Doc Highlights**
+
+- HTTP: `GET /api/v1/global-context/doc/{doc_type}/highlights`
+- operationId: `get_doc_highlights_global_context_doc__doc_type__highlights_get` (also callable as `g8.api.call("get_doc_highlights_global_context_doc__doc_type__highlights_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The short, quotable points from a completed document.
+
+Built for grounding a chat turn without sending the whole document, so this
+is the cheap read when you need a few facts rather than the text.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_type` | `string` | yes | Document type key, e.g. `company_profile`, `icp_research`, `buying_journey`. Free-form on purpose: the set grows with the product and a closed list here would 422 a document the org already has. |
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.getDocHighlights({ path: { doc_type: "example" } });
+```
+
+---
+
+<a id="op-getdocumentsanalytics"></a>
+
+### `g8.api.gtmContext.getDocumentsAnalytics(input?)`
+
+**Get Documents Analytics**
+
+- HTTP: `GET /api/v1/global-context/documents/analytics`
+- operationId: `get_documents_analytics_global_context_documents_analytics_get` (also callable as `g8.api.call("get_documents_analytics_global_context_documents_analytics_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Every document with its usage counts.
+
+Declared before `/documents/{doc_id}`: the parameter route would otherwise
+match first and try to load a document called "analytics".
+
+The answer to "which Studio documents are actually being read" - the input
+to deciding what to regenerate and what to delete.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioListPayload_`: the envelope `{ data: StudioListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`StudioListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.getDocumentsAnalytics();
+```
+
+---
+
+<a id="op-getglobalcontextdocument"></a>
+
+### `g8.api.gtmContext.getGlobalContextDocument(input)`
+
+**Get Global Context Document**
+
+- HTTP: `GET /api/v1/global-context/documents/{doc_id}`
+- operationId: `get_global_context_document_global_context_documents__doc_id__get` (also callable as `g8.api.call("get_global_context_document_global_context_documents__doc_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+One document, with its full content.
+
+`GET /global-context/documents` lists them; this returns a single one by id
+or by type key.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_id` | `string` | yes | Document id, OR a document TYPE key. The app resolves either, which is what makes `company_profile` a usable id. |
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.getGlobalContextDocument({ path: { doc_id: "id" } });
+```
+
+---
+
+<a id="op-getlatestpipeline"></a>
+
+### `g8.api.gtmContext.getLatestPipeline(input?)`
+
+**Get Latest Pipeline**
+
+- HTTP: `GET /api/v1/global-context/pipeline/latest`
+- operationId: `get_latest_pipeline_global_context_pipeline_latest_get` (also callable as `g8.api.call("get_latest_pipeline_global_context_pipeline_latest_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The most recent run.
+
+Declared before `/pipeline/{pipeline_id}` so the literal wins - otherwise
+the id route matches "latest" and looks for a pipeline with that id.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.getLatestPipeline();
+```
+
+---
+
+<a id="op-getmailboxwarmupanalytics"></a>
+
+### `g8.api.gtmContext.getMailboxWarmupAnalytics(input)`
+
+**Get Mailbox Warmup Analytics**
+
+- HTTP: `GET /api/v1/mailboxes/{mailbox_id}/warmup`
+- operationId: `get_mailbox_warmup_analytics_mailboxes__mailbox_id__warmup_get` (also callable as `g8.api.call("get_mailbox_warmup_analytics_mailboxes__mailbox_id__warmup_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+- ★ Hand-written: [`g8.mailboxes.warmup()`](../sdk-clients.md#g8-mailboxes-warmup)
+
+Get live warmup analytics for a single mailbox.
+
+Wraps the existing ``GET /warmup/{mailbox_id}/analytics`` flow so MCP
+(API-key auth) can read warmup engagement / reputation without going
+through cookie-based session auth.
+
+Behavior:
+    - Looks up the mailbox in the API user's org schema. 404 if missing
+      or deleted. Tenant isolation comes from the per-org schema bind,
+      NOT from a row-level predicate.
+    - Hits the configured warmup provider (Instantly or SmartLead) over
+      HTTP — slow (~300-800ms typical). For warm bulk reads use
+      ``list_mailboxes`` and check the cheap DB-level ``warmup_status``.
+    - Returns ``{success, warmup_enabled, provider, analytics, warmup_settings}``
+      — same shape as the internal /warmup/{id}/analytics endpoint.
+
+Backwards-compat: this is a brand-new route. The internal
+/warmup/{id}/analytics (cookie auth) is unchanged.
+
+Historical bug (fixed 2026-05-24, same root cause as list_mailboxes
+above): the previous implementation appended
+``(t.org_id = :org_id OR m.created_by = :user_id)`` to the WHERE. Both
+halves match zero rows in prod — ``mailboxes.team_id`` is NULL on every
+row (no team pinning) and ``mailboxes.created_by`` stores email strings,
+not propelauth UUIDs. Result: every warmup-analytics call 404'd even
+for mailboxes that ``list_mailboxes`` happily returned. Dropping the
+predicate restores parity; schema bind is the tenant boundary.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.mailbox_id` | `integer` | yes |  |
+
+**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.gtmContext.getMailboxWarmupAnalytics({ path: { mailbox_id: 123 } });
+```
+
+---
+
+<a id="op-getpipelinestatus"></a>
+
+### `g8.api.gtmContext.getPipelineStatus(input)`
+
+**Get Pipeline Status**
+
+- HTTP: `GET /api/v1/global-context/pipeline/{pipeline_id}`
+- operationId: `get_pipeline_status_global_context_pipeline__pipeline_id__get` (also callable as `g8.api.call("get_pipeline_status_global_context_pipeline__pipeline_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Per-document status for ONE run.
+
+This is where a stalled generation is diagnosed: which documents completed,
+which are still generating, and which failed with what.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.pipeline_id` | `string` | yes | Pipeline id. |
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.getPipelineStatus({ path: { pipeline_id: "id" } });
+```
+
+---
+
+<a id="op-listactivities"></a>
+
+### `g8.api.gtmContext.listActivities(input?)`
+
+**List Activities**
+
+- HTTP: `GET /api/v1/activities`
+- operationId: `list_activities_activities_get` (also callable as `g8.api.call("list_activities_activities_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+List recent activities for the authenticated organization.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.page` | `integer` | no | default `1` |
+| `query.limit` | `integer` | no | default `50` |
+| `query.activity_type` | `string \| null` | no |  |
+| `query.contact_id` | `string \| null` | no |  |
+| `query.company_id` | `string \| null` | no |  |
+| `query.mashup_contact_id` | `integer \| null` | no |  |
+| `query.mashup_company_id` | `integer \| null` | no |  |
+| `query.deal_id` | `string \| null` | no |  |
+| `query.occurred_after` | `string (date-time) \| null` | no |  |
+| `query.occurred_before` | `string (date-time) \| null` | no |  |
+
+**Returns** `ApiResponse_list_dict__`: the envelope `{ data: Array<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.gtmContext.listActivities();
+```
+
+---
+
+<a id="op-listglobalcontextdocuments"></a>
+
+### `g8.api.gtmContext.listGlobalContextDocuments(input?)`
+
+**List Global Context Documents**
+
+- HTTP: `GET /api/v1/global-context/documents`
+- operationId: `list_global_context_documents_global_context_documents_get` (also callable as `g8.api.call("list_global_context_documents_global_context_documents_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+- ★ Hand-written: [`g8.studio.globalContext()`](../sdk-clients.md#g8-studio-globalcontext)
+
+List global context documents for the authenticated organization.
+
+Each row carries metadata (id, display_name, file_type, category,
+folder_path, status, priority, version, timestamps). When
+``include_content`` is True (the default) the document body is included at
+``content`` (sourced from ``meta_data.content``) so callers can read what a
+document actually says; pass ``include_content=false`` to omit the body for
+a cheaper listing. The default stays True for backwards compatibility — the
+MCP ``g8_gtm_get_global_context`` tool, the JS SDK ``studio.globalContext``
+client, and the ``g8://global-context`` resource surfaces have always relied
+on ``content`` being present.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.category` | `string \| null` | no | Filter by context category |
+| `query.include_content` | `boolean` | no | Include each document's body text at `content` (read from meta_data.content). Default True preserves historical behavior (this endpoint has always returned content); pass false for a lighter metadata-only listing. default `true` |
+| `query.limit` | `integer` | no | default `50` |
+
+**Returns** `ApiResponse_list_dict__`: the envelope `{ data: Array<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.gtmContext.listGlobalContextDocuments();
+```
+
+---
+
+<a id="op-listicps"></a>
+
+### `g8.api.gtmContext.listIcps(input?)`
+
+**List Icps**
+
+- HTTP: `GET /api/v1/icps`
+- operationId: `list_icps_icps_get` (also callable as `g8.api.call("list_icps_icps_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+- ★ Hand-written: [`g8.studio.icps()`](../sdk-clients.md#g8-studio-icps)
+
+List campaign-builder ICPs for the authenticated organization.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.status` | `string \| null` | no | Filter by ICP status |
+| `query.limit` | `integer` | no | default `50` |
+
+**Returns** `ApiResponse_list_dict__`: the envelope `{ data: Array<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.gtmContext.listIcps();
+```
+
+---
+
+<a id="op-listintelligencedata"></a>
+
+### `g8.api.gtmContext.listIntelligenceData(input?)`
+
+**List Intelligence Data**
+
+- HTTP: `GET /api/v1/intelligence-data`
+- operationId: `list_intelligence_data_intelligence_data_get` (also callable as `g8.api.call("list_intelligence_data_intelligence_data_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+- ★ Hand-written: [`g8.studio.intelligenceData()`](../sdk-clients.md#g8-studio-intelligencedata)
+
+List intelligence-data documents (the ~16 docs in the Intelligence bucket).
+
+Part of the 44-document Studio Global Document Architecture (21 context +
+16 intelligence + 6 research + 1 brief). The MCP campaign-ideation path
+needs this bucket — historically only the ``cb_global_contexts`` (Context)
+bucket was exposed via REST.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.data_type` | `string \| null` | no | Filter by data_type (website_scrape, company_enrichment, competitor_discovery, company_keywords, product_inventory, organic_keywords, paid_keywords, ...) |
+| `query.include_content` | `boolean` | no | Include the raw `data` JSONB blob (large; default omits) default `false` |
+| `query.limit` | `integer` | no | default `50` |
+
+**Returns** `ApiResponse_list_dict__`: the envelope `{ data: Array<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.gtmContext.listIntelligenceData();
+```
+
+---
+
+<a id="op-listmailboxes"></a>
+
+### `g8.api.gtmContext.listMailboxes(input?)`
+
+**List Mailboxes**
+
+- HTTP: `GET /api/v1/mailboxes`
+- operationId: `list_mailboxes_mailboxes_get` (also callable as `g8.api.call("list_mailboxes_mailboxes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+- ★ Hand-written: [`g8.mailboxes.list()`](../sdk-clients.md#g8-mailboxes-list)
+
+List sending mailboxes the authenticated user can access in this org.
+
+Backs the MCP "pick a mailbox before launching a campaign" flow.
+
+Sources from the canonical ``mailboxes`` table (NOT the
+``ai_inbox_email_cron_jobs`` table the FE picker previously used — that
+table is the AI-inbox sync state, not the source of truth for which
+mailboxes exist). See ``.claude/agent-context/mailbox-picker-sources-cron-table.md``.
+
+Tenant scope: ``mailboxes`` lives in the per-org schema (NOT public —
+the earlier version of this comment was wrong; see
+``select to_regclass('public.mailboxes')`` returning null vs. the
+per-org row count). Binding the session to ``schema=<org>`` IS the
+tenant boundary; no further org-filter predicate is needed.
+
+Per-row RBAC (``ENFORCE_MAILBOX_PERMISSIONS`` soak flag) is NOT enforced
+here yet — Phase 3b on issue #7180 — keeping symmetry with the FE
+picker. When that flag flips on, this endpoint will adopt the scope
+filter alongside the cdp/mailboxes/fetch surface.
+
+Historical bug (fixed 2026-05-22): the previous implementation appended
+``(t.org_id = :org_id OR m.created_by = :user_id)`` to the WHERE. Both
+halves silently matched zero rows in prod — ``mailboxes.team_id`` is
+NULL on every row (no team pinning) and ``mailboxes.created_by`` stores
+email strings, not propelauth UUIDs. Result: the endpoint returned an
+empty list for every caller. Dropping the predicate restores the
+correct per-org listing; tenant isolation comes from the schema bind.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.limit` | `integer` | no | default `100` |
+| `query.include_archived` | `boolean` | no | Include archived mailboxes default `false` |
+| `query.connection_status` | `string \| null` | no | Filter by connection_status (active\|paused\|disconnected\|expired\|...) |
+
+**Returns** `ApiResponse_list_dict__`: the envelope `{ data: Array<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.gtmContext.listMailboxes();
+```
+
+---
+
+<a id="op-listpersonas"></a>
+
+### `g8.api.gtmContext.listPersonas(input?)`
+
+**List Personas**
+
+- HTTP: `GET /api/v1/personas`
+- operationId: `list_personas_personas_get` (also callable as `g8.api.call("list_personas_personas_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+- ★ Hand-written: [`g8.studio.personas()`](../sdk-clients.md#g8-studio-personas)
+
+List campaign-builder personas for the authenticated organization.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.status` | `string \| null` | no | Filter by persona status |
+| `query.limit` | `integer` | no | default `50` |
+
+**Returns** `ApiResponse_list_dict__`: the envelope `{ data: Array<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.gtmContext.listPersonas();
+```
+
+---
+
+<a id="op-listpipelines"></a>
+
+### `g8.api.gtmContext.listPipelines(input?)`
+
+**List Pipelines**
+
+- HTTP: `GET /api/v1/global-context/pipelines`
+- operationId: `list_pipelines_global_context_pipelines_get` (also callable as `g8.api.call("list_pipelines_global_context_pipelines_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Recent Global Context generation runs, newest first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.limit` | `integer` | no | How many recent runs to return. The app's default is 10. default `10` |
+
+**Returns** `ApiResponse_StudioListPayload_`: the envelope `{ data: StudioListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`StudioListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.listPipelines();
+```
+
+---
+
+<a id="op-listresearchreports"></a>
+
+### `g8.api.gtmContext.listResearchReports(input?)`
+
+**List Research Reports**
+
+- HTTP: `GET /api/v1/research-reports`
+- operationId: `list_research_reports_research_reports_get` (also callable as `g8.api.call("list_research_reports_research_reports_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+- ★ Hand-written: [`g8.studio.researchReports()`](../sdk-clients.md#g8-studio-researchreports)
+
+List research-report documents (the 6 docs in the Research bucket).
+
+Part of the 44-document Studio Global Document Architecture (21 context +
+16 intelligence + 6 research + 1 brief). The MCP ideation path needs this
+bucket alongside ``/intelligence-data`` to surface the full picture.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.report_type` | `string \| null` | no | Filter by report_type (buyer_psychology, competitive_teardown, gtm_channel, industry_analyst, review_sentiment, voice_of_customer) |
+| `query.include_content` | `boolean` | no | Include the structured `content` JSONB blob + markdown (large) default `false` |
+| `query.limit` | `integer` | no | default `50` |
+
+**Returns** `ApiResponse_list_dict__`: the envelope `{ data: Array<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.gtmContext.listResearchReports();
+```
+
+---
+
+<a id="op-regenerateglobalcontext"></a>
+
+### `g8.api.gtmContext.regenerateGlobalContext(input)`
+
+**Regenerate Global Context**
+
+- HTTP: `POST /api/v1/global-context/regenerate`
+- operationId: `regenerate_global_context_global_context_regenerate_post` (also callable as `g8.api.call("regenerate_global_context_global_context_regenerate_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Regenerate Studio (Global Context) documents against a website.
+
+**Why this exists.** Studio docs are generated once at onboarding from the
+company profile's website. If that profile was wrong at the time — the common
+case for self-serve orgs, which seed graph8's own profile when no domain is
+given — every downstream ICP, persona, TAM and campaign is built on the wrong
+company, and there was no machine path to fix it:
+
+* the internal ``POST /global-context/generate-all`` refuses forever once the
+  first pipeline completes (``409 ... Contact support to reset and regenerate``);
+* ``POST /global-context/generate/{doc_type}`` has no such lock but was
+  JWT-only, so an agent or API key could not call it.
+
+This endpoint wraps the per-document path, which means it is **not** subject to
+the one-shot pipeline lock and can be run whenever the source of truth changes.
+
+Requires intelligence data for ``website_url`` to exist already — run the
+intelligence analyze step first for a newly-changed domain, otherwise this
+returns 404 rather than regenerating stale content.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `RegenerateContextRequest` | yes | Request body; fields below. |
+
+Body fields (`RegenerateContextRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.website_url` | `string` | yes | Website to generate from. After a company-profile change this must be the NEW domain — intelligence is keyed by URL, so passing the old one silently regenerates the same stale content. |
+| `body.doc_types` | `Array<string> \| null` | no | Specific Studio doc types to regenerate (e.g. ['icp_research','persona_research']). Omit to regenerate every document that already exists in the org. |
+
+**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.gtmContext.regenerateGlobalContext({ body: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-regenerateonedocument"></a>
+
+### `g8.api.gtmContext.regenerateOneDocument(input)`
+
+**Regenerate One Document**
+
+- HTTP: `POST /api/v1/global-context/{doc_id}/regenerate`
+- operationId: `regenerate_one_document_global_context__doc_id__regenerate_post` (also callable as `g8.api.call("regenerate_one_document_global_context__doc_id__regenerate_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Rewrite ONE document with AI, from the current intelligence data.
+
+Different from `POST /global-context/regenerate`, which rebuilds a SET
+against a website: this takes a single document id and rewrites it in
+place. The old content is replaced.
+
+Declared LAST on this router. `{doc_id}` occupies the same segment as every
+literal above it, so registered earlier it would swallow `/pipelines`,
+`/scaffold` and the rest.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_id` | `string` | yes | Document id. |
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.regenerateOneDocument({ path: { doc_id: "id" } });
+```
+
+---
+
+<a id="op-reindexalldocuments"></a>
+
+### `g8.api.gtmContext.reindexAllDocuments(input?)`
+
+**Reindex All Documents**
+
+- HTTP: `POST /api/v1/global-context/reindex-all`
+- operationId: `reindex_all_documents_global_context_reindex_all_post` (also callable as `g8.api.call("reindex_all_documents_global_context_reindex_all_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Re-index every document into retrieval.
+
+Changes no document. It rebuilds the index the copilot and campaign
+generation search, which is the fix when a document reads correctly in the
+library but never shows up as grounding.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.reindexAllDocuments();
+```
+
+---
+
+<a id="op-reindexcompanyprofile"></a>
+
+### `g8.api.gtmContext.reindexCompanyProfile(input)`
+
+**Reindex Company Profile**
+
+- HTTP: `POST /api/v1/company-profile/reindex`
+- operationId: `reindex_company_profile_company_profile_reindex_post` (also callable as `g8.api.call("reindex_company_profile_company_profile_reindex_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Rebuild the search index over this profile. SPENDS PROVIDER BUDGET.
+
+Every call re-embeds the whole profile through the embedding provider -
+there is no dedupe, and the cost is proportional to how much is in the
+profile rather than to what changed. Tiered `billable` for that reason.
+
+Worth calling after a profile edit: the published `PUT /company-profile`
+writes the row but does NOT re-index, so anything that reads the profile
+through search stays stale until this runs.
+
+The website is taken in the BODY here. The app reads it as a query
+parameter on a POST, which is the kind of detail that only bites once.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ProfileWebsiteRequest` | yes | Request body; fields below. |
+
+Body fields (`ProfileWebsiteRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.website_url` | `string` | yes | Website the profile was built from. Matched on its canonical domain. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.gtmContext.reindexCompanyProfile({ body: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-resetcompanyprofilekeywords"></a>
+
+### `g8.api.gtmContext.resetCompanyProfileKeywords(input)`
+
+**Reset Company Profile Keywords**
+
+- HTTP: `DELETE /api/v1/company-profile/keywords`
+- operationId: `reset_company_profile_keywords_company_profile_keywords_delete` (also callable as `g8.api.call("reset_company_profile_keywords_company_profile_keywords_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Delete the keywords derived for this profile. NOT REVERSIBLE.
+
+A hard delete with no soft-delete row behind it: the keywords are gone and
+the only way back is to regenerate them. Returns how many were removed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.website_url` | `string` | yes | The website the profile was built from. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.gtmContext.resetCompanyProfileKeywords({ query: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-resetstuckdocuments"></a>
+
+### `g8.api.gtmContext.resetStuckDocuments(input?)`
+
+**Reset Stuck Documents**
+
+- HTTP: `POST /api/v1/global-context/reset-stuck-documents`
+- operationId: `reset_stuck_documents_global_context_reset_stuck_documents_post` (also callable as `g8.api.call("reset_stuck_documents_global_context_reset_stuck_documents_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Move documents wedged in `generating` back to a state you can act on.
+
+A document whose worker died stays `generating` forever and blocks a
+retry. This unblocks them; it does not generate anything.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `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.gtmContext.resetStuckDocuments();
+```
+
+---
+
+<a id="op-resumepipeline"></a>
+
+### `g8.api.gtmContext.resumePipeline(input?)`
+
+**Resume Pipeline**
+
+- HTTP: `POST /api/v1/global-context/resume-pipeline`
+- operationId: `resume_pipeline_global_context_resume_pipeline_post` (also callable as `g8.api.call("resume_pipeline_global_context_resume_pipeline_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Finish a run that stopped part way, generating only what is missing.
+
+The repair for a pipeline that died mid-way. It does NOT rebuild documents
+that already completed, so it is cheap and safe to retry.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.resumePipeline();
+```
+
+---
+
+<a id="op-retrycompanyprofile"></a>
+
+### `g8.api.gtmContext.retryCompanyProfile(input)`
+
+**Retry Company Profile**
+
+- HTTP: `POST /api/v1/company-profile/retry`
+- operationId: `retry_company_profile_company_profile_retry_post` (also callable as `g8.api.call("retry_company_profile_company_profile_retry_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Delete the profile and generate it again from intelligence. SPENDS CREDITS.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ProfileWebsiteRequest` | yes | Request body; fields below. |
+
+Body fields (`ProfileWebsiteRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.website_url` | `string` | yes | Website the profile was built from. Matched on its canonical domain. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.gtmContext.retryCompanyProfile({ body: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-savebuyingjourneyinterview"></a>
+
+### `g8.api.gtmContext.saveBuyingJourneyInterview(input)`
+
+**Save Buying Journey Interview**
+
+- HTTP: `POST /api/v1/global-context/documents/buying-journey/interview`
+- operationId: `save_buying_journey_interview_global_context_documents_buying_journey_interview_post` (also callable as `g8.api.call("save_buying_journey_interview_global_context_documents_buying_journey_interview_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Record how this organisation actually sells, in its own words.
+
+The answers are injected as HIGHEST-PRIORITY grounding the next time the
+buying journey is generated - they outrank the scraped and inferred
+material. The document must already exist; this grounds it, it does not
+create it.
+
+Declared with a literal `buying-journey` second segment, so it does not
+collide with `/documents/{doc_id}/feedback`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `BuyingJourneyInterviewRequest` | yes | Request body; fields below. |
+
+Body fields (`BuyingJourneyInterviewRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.answers` | `Record<string, unknown>` | yes | Structured interview answers about how this organisation sells. Injected as highest-priority grounding the next time the buying journey document is generated. |
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.saveBuyingJourneyInterview({ body: { answers: {} } });
+```
+
+---
+
+<a id="op-scaffoldalldocuments"></a>
+
+### `g8.api.gtmContext.scaffoldAllDocuments(input?)`
+
+**Scaffold All Documents**
+
+- HTTP: `POST /api/v1/global-context/scaffold`
+- operationId: `scaffold_all_documents_global_context_scaffold_post` (also callable as `g8.api.call("scaffold_all_documents_global_context_scaffold_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Create every Global Context document as an EMPTY template.
+
+Scaffolding is not generation: it creates the rows so the library has a
+shape, and leaves them empty. Useful when you want to fill documents
+yourself through `PATCH /global-context/documents/{doc_id}` rather than
+have them written for you.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.scaffoldAllDocuments();
+```
+
+---
+
+<a id="op-scaffoldcompanykeywords"></a>
+
+### `g8.api.gtmContext.scaffoldCompanyKeywords(input?)`
+
+**Scaffold Company Keywords**
+
+- HTTP: `POST /api/v1/global-context/scaffold-company-keywords`
+- operationId: `scaffold_company_keywords_global_context_scaffold_company_keywords_post` (also callable as `g8.api.call("scaffold_company_keywords_global_context_scaffold_company_keywords_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Create the Company Keywords template in the brand category. IDEMPOTENT.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.scaffoldCompanyKeywords();
+```
+
+---
+
+<a id="op-scaffoldcompanyprofile"></a>
+
+### `g8.api.gtmContext.scaffoldCompanyProfile(input?)`
+
+**Scaffold Company Profile**
+
+- HTTP: `POST /api/v1/global-context/scaffold-company-profile`
+- operationId: `scaffold_company_profile_global_context_scaffold_company_profile_post` (also callable as `g8.api.call("scaffold_company_profile_global_context_scaffold_company_profile_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Create the `company_profile` template if it does not exist.
+
+IDEMPOTENT - an org that already has one gets the existing document back
+rather than a second copy. The company profile is the root of the
+dependency graph, so this is the one to create first when a library is
+missing it.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.scaffoldCompanyProfile();
+```
+
+---
+
+<a id="op-stopallgeneration"></a>
+
+### `g8.api.gtmContext.stopAllGeneration(input?)`
+
+**Stop All Generation**
+
+- HTTP: `POST /api/v1/global-context/stop-all-generation`
+- operationId: `stop_all_generation_global_context_stop_all_generation_post` (also callable as `g8.api.call("stop_all_generation_global_context_stop_all_generation_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Stop every in-flight generation for this organisation, immediately.
+
+The kill switch. Work already done is kept; work in flight is abandoned,
+so a document caught mid-write comes back as failed rather than partial.
+
+**Input**: none.
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.stopAllGeneration();
+```
+
+---
+
+<a id="op-submitdocumentfeedback"></a>
+
+### `g8.api.gtmContext.submitDocumentFeedback(input)`
+
+**Submit Document Feedback**
+
+- HTTP: `POST /api/v1/global-context/documents/{doc_id}/feedback`
+- operationId: `submit_document_feedback_global_context_documents__doc_id__feedback_post` (also callable as `g8.api.call("submit_document_feedback_global_context_documents__doc_id__feedback_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Thumbs up or down on a document.
+
+`usage_id` attaches the feedback to a specific USE of the document rather
+than to the document itself, which is what makes "this answer was wrong"
+distinguishable from "this document is wrong".
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_id` | `string` | yes | Document id. |
+| `body` | `DocumentFeedbackRequest` | yes | Request body; fields below. |
+
+Body fields (`DocumentFeedbackRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.feedback_type` | `"up" \| "down"` | yes | Thumbs up or thumbs down on the document. |
+| `body.usage_id` | `string \| null` | no | The usage record this feedback is about, when the feedback follows a specific use of the document rather than the document itself. |
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.submitDocumentFeedback({ path: { doc_id: "id" }, body: { feedback_type: "up" } });
+```
+
+---
+
+<a id="op-trackdocumentusage"></a>
+
+### `g8.api.gtmContext.trackDocumentUsage(input)`
+
+**Track Document Usage**
+
+- HTTP: `POST /api/v1/global-context/documents/{doc_id}/track-usage`
+- operationId: `track_document_usage_global_context_documents__doc_id__track_usage_post` (also callable as `g8.api.call("track_document_usage_global_context_documents__doc_id__track_usage_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Record one use of a Global Context document.
+
+Feeds `GET /global-context/documents/analytics`. 404 if the document does
+not exist in the caller's organisation.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_id` | `string` | yes | Global Context document ID. |
+| `body` | `TrackDocumentUsageRequest` | yes | Request body; fields below. |
+
+Body fields (`TrackDocumentUsageRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.usage_type` | `"creation" \| "citation"` | yes | `creation`: the document was used to generate new content. `citation`: the document was quoted or referenced. |
+| `body.source_id` | `string \| null` | no | ID of the entity that used the document, if any. max length 128 |
+| `body.source_type` | `string \| null` | no | Where the use happened, e.g. `campaign`, `account`, `copilot`, `research`. Free-form. max length 64 |
+
+**Returns** `ApiResponse_StudioPayload_`: the envelope `{ data: StudioPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.trackDocumentUsage({ path: { doc_id: "id" }, body: { usage_type: "creation" } });
+```
+
+---
+
+<a id="op-unapprovecompanyprofile"></a>
+
+### `g8.api.gtmContext.unapproveCompanyProfile(input)`
+
+**Unapprove Company Profile**
+
+- HTTP: `POST /api/v1/company-profile/unapprove`
+- operationId: `unapprove_company_profile_company_profile_unapprove_post` (also callable as `g8.api.call("unapprove_company_profile_company_profile_unapprove_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Release a human's approval on the profile so it can be rewritten.
+
+An approved profile is immutable through `PUT /company-profile` unless
+that call is sent with `unapprove_if_approved`. This is the standalone
+half: it clears the approval WITHOUT changing a field, which is what you
+want when the approval was premature rather than the content wrong.
+
+Org-wide and immediate. Nothing re-approves automatically.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ProfileWebsiteRequest` | yes | Request body; fields below. |
+
+Body fields (`ProfileWebsiteRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.website_url` | `string` | yes | Website the profile was built from. Matched on its canonical domain. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.unapproveCompanyProfile({ body: { website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-updatecompanyprofile"></a>
+
+### `g8.api.gtmContext.updateCompanyProfile(input)`
+
+**Update Company Profile**
+
+- HTTP: `PUT /api/v1/company-profile`
+- operationId: `update_company_profile_company_profile_put` (also callable as `g8.api.call("update_company_profile_company_profile_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Set this org's company profile (website + fields).
+
+**Why this exists.** The company profile is the source of truth for Studio
+generation. Self-serve orgs that sign up without a domain get a profile seeded
+with graph8's own details, so every generated document describes the wrong
+company — and the only write path was ``POST /company-profile``, an internal
+JWT route absent from both the developer API and MCP. An agent could therefore
+detect the problem but never fix it, and could not even read the field back to
+confirm a human had fixed it.
+
+Approved profiles are immutable. Pass ``unapprove_if_approved: true`` to
+deliberately unlock and overwrite one; otherwise this returns 409 rather than
+quietly discarding a human's approval.
+
+Changing the website does NOT regenerate existing Studio documents — they were
+generated from the old site. Follow with
+``POST /api/v1/global-context/regenerate``.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CompanyProfileUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`CompanyProfileUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.fields` | `Record<string, string>` | yes | Profile fields to save, e.g. {'company_name': 'Acme', 'industry': 'Manufacturing'}. Replaces the stored field set. |
+| `body.website_url` | `string` | yes | The client's real website. This is the source of truth Studio generation reads; setting it wrong is what makes every downstream ICP, persona and campaign describe the wrong company. |
+| `body.unapprove_if_approved` | `boolean` | no | Approved profiles are immutable by design. Set true to explicitly unlock and overwrite a human-approved profile. Left false, an approved profile returns 409 instead of being silently unapproved. default `false` |
+
+**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.gtmContext.updateCompanyProfile({ body: { fields: {}, website_url: "https://example.com" } });
+```
+
+---
+
+<a id="op-updateglobalcontextdocument"></a>
+
+### `g8.api.gtmContext.updateGlobalContextDocument(input)`
+
+**Update Global Context Document**
+
+- HTTP: `PATCH /api/v1/global-context/documents/{doc_id}`
+- operationId: `update_global_context_document_global_context_documents__doc_id__patch` (also callable as `g8.api.call("update_global_context_document_global_context_documents__doc_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Update a Global Context (Studio) document's content and/or status.
+
+Read-side counterpart already exists (``GET /global-context/documents``);
+this closes the long-standing "read but can't update" gap for the Context
+bucket. Each save creates a ``DocumentVersion`` snapshot, identical to the
+internal Studio editor — so version history stays consistent regardless of
+whether the edit came from the UI, the developer API, or MCP.
+
+Partial update: send ``content``, ``status``, or both. Returns 400 if
+neither is provided, 404 if the document does not exist in this org.
+
+Note: the Intelligence bucket (``cb_intelligence_data``) is intentionally
+read-only — it is machine-generated and has no manual-edit path.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.doc_id` | `string` | yes | Global context document ID (UUID) |
+| `body` | `UpdateGlobalContextRequest` | yes | Request body; fields below. |
+
+Body fields (`UpdateGlobalContextRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.content` | `string \| null` | no | New document body. Stored at meta_data.content. Omit to leave unchanged. |
+| `body.status` | `string \| null` | no | New document status (e.g. 'completed', 'draft'). Omit to leave unchanged. |
+
+**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.gtmContext.updateGlobalContextDocument({ path: { doc_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updateicp"></a>
+
+### `g8.api.gtmContext.updateIcp(input)`
+
+**Update Icp**
+
+- HTTP: `PATCH /api/v1/icps/{icp_id}`
+- operationId: `update_icp_icps__icp_id__patch` (also callable as `g8.api.call("update_icp_icps__icp_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+- ★ Hand-written: [`g8.studio.updateIcp()`](../sdk-clients.md#g8-studio-updateicp)
+
+Update a Studio ICP's fields (partial update).
+
+Send at least one field. To archive an ICP use ``POST /icps/{icp_id}/archive``.
+Returns 400 if no field is provided, 404 if the ICP does not exist in this org.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.icp_id` | `string` | yes | ICP ID (UUID) |
+| `body` | `UpdateIcpRequest` | yes | Request body; fields below. |
+
+Body fields (`UpdateIcpRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.buying_signals` | `Array<unknown> \| null` | no | New list of buying-intent signals. |
+| `body.description` | `string \| null` | no | New description. |
+| `body.estimated_market_size` | `integer \| null` | no | New estimated market-size count. |
+| `body.firmographics` | `Record<string, unknown> \| null` | no | New firmographic criteria. |
+| `body.name` | `string \| null` | no | New ICP name. |
+| `body.tech_stack` | `Record<string, unknown> \| null` | no | New technology signals. |
+
+**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.gtmContext.updateIcp({ path: { icp_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updatepersona"></a>
+
+### `g8.api.gtmContext.updatePersona(input)`
+
+**Update Persona**
+
+- HTTP: `PATCH /api/v1/personas/{persona_id}`
+- operationId: `update_persona_personas__persona_id__patch` (also callable as `g8.api.call("update_persona_personas__persona_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+- ★ Hand-written: [`g8.studio.updatePersona()`](../sdk-clients.md#g8-studio-updatepersona)
+
+Update a Studio persona's fields and/or status (partial update).
+
+Send at least one field. Passing ``status='archived'`` is equivalent to
+``POST /personas/{persona_id}/archive``. Returns 400 if no field is provided,
+404 if the persona does not exist in this org.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.persona_id` | `string` | yes | Persona ID (UUID) |
+| `body` | `UpdatePersonaRequest` | yes | Request body; fields below. |
+
+Body fields (`UpdatePersonaRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.campaign_approach` | `string \| null` | no | New campaign approach. |
+| `body.confidence` | `string \| null` | no | New confidence label. |
+| `body.expected_receptivity` | `string \| null` | no | New expected-receptivity note. |
+| `body.key_signals` | `Array<unknown> \| null` | no | New list of buying/intent signals. |
+| `body.priority` | `integer \| null` | no | New display priority. |
+| `body.recommended_goal` | `string \| null` | no | New recommended goal. |
+| `body.status` | `string \| null` | no | New status (e.g. 'active', 'archived'). |
+| `body.title` | `string \| null` | no | New persona title. |
+| `body.why_target` | `string \| null` | no | New 'why target' text. |
+
+**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.gtmContext.updatePersona({ path: { persona_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updateresearchreport"></a>
+
+### `g8.api.gtmContext.updateResearchReport(input)`
+
+**Update Research Report**
+
+- HTTP: `PATCH /api/v1/research-reports/{report_id}`
+- operationId: `update_research_report_research_reports__report_id__patch` (also callable as `g8.api.call("update_research_report_research_reports__report_id__patch", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `campaigns:run`
+
+Update a Research report's markdown content and/or status.
+
+Read-side counterpart already exists (``GET /research-reports``); this
+closes the "read but can't update" gap for the Research bucket. On a content
+change it creates a ``DocumentVersion`` snapshot AND re-indexes the report to
+the RAG knowledge base — identical to the internal Studio editor, so search
+never goes stale relative to an API-driven edit.
+
+Partial update: send ``markdown_content``, ``status``, or both. Returns 400
+if neither is provided, 404 if the report does not exist in this org. A
+report already 'completed'/'approved' can only move between those two states.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.report_id` | `string` | yes | Research report ID (UUID) |
+| `body` | `UpdateResearchReportRequest` | yes | Request body; fields below. |
+
+Body fields (`UpdateResearchReportRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.markdown_content` | `string \| null` | no | New rendered markdown body. Omit to leave unchanged. Triggers RAG re-index. |
+| `body.status` | `string \| null` | no | New report status. A report already 'completed'/'approved' can only move between those two states (done reports stay done). |
+
+**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
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.gtmContext.updateResearchReport({ path: { report_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-uploadcompanyprofilelogo"></a>
+
+### `g8.api.gtmContext.uploadCompanyProfileLogo(input?)`
+
+**Upload Company Profile Logo**
+
+- HTTP: `POST /api/v1/company-profile/logo`
+- operationId: `upload_company_profile_logo_company_profile_logo_post` (also callable as `g8.api.call("upload_company_profile_logo_company_profile_logo_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Upload the org's logo and set it on the profile. Multipart.
+
+The public booking page shows this logo.
+
+**Input**: none.
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.gtmContext.uploadCompanyProfileLogo();
+```
+
+---
+
+<a id="op-uploadenablementasset"></a>
+
+### `g8.api.gtmContext.uploadEnablementAsset(input)`
+
+**Upload Enablement Asset**
+
+- HTTP: `POST /api/v1/enablement/assets`
+- operationId: `upload_enablement_asset_enablement_assets_post` (also callable as `g8.api.call("upload_enablement_asset_enablement_assets_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Upload an internal, org-scoped asset to Studio's Enablement library.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `EnablementAssetUploadRequest` | yes | Request body; fields below. |
+
+Body fields (`EnablementAssetUploadRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.content_base64` | `string` | yes | min length 1 |
+| `body.file_name` | `string` | yes | min length 1, max length 255 |
+| `body.folder` | `string \| null` | no | max length 50 |
+| `body.mime_type` | `string \| null` | no | max length 100 |
+| `body.tags` | `Array<string>` | no | max items 20 |
+
+**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.gtmContext.uploadEnablementAsset({ body: { content_base64: "example", file_name: "Example" } });
+```