@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/brandKit.md

@@ -0,0 +1,1133 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.brandKit`: Brand Kit
+
+30 operations (17 read, 12 write, 1 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.brandKit.*` 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: [brandKit.d.ts](brandKit.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`createCustomLayoutTemplate`](#op-createcustomlayouttemplate) | `POST /api/v1/brand-kit/layout-templates/custom` | write | `campaigns:write` | Create Custom Layout Template |
+| [`deleteBrandKitTemplates`](#op-deletebrandkittemplates) | `DELETE /api/v1/brand-kit/templates` | destructive | `campaigns:delete` | Delete Brand Kit Templates |
+| [`getBrandKitHomepage`](#op-getbrandkithomepage) | `GET /api/v1/brand-kit/homepage` | read | `campaigns:read` | Get Brand Kit Homepage |
+| [`getBrandKitOverview`](#op-getbrandkitoverview) | `GET /api/v1/brand-kit` | read | `campaigns:read` | Get Brand Kit Overview |
+| [`getBrandKitTemplates`](#op-getbrandkittemplates) | `GET /api/v1/brand-kit/templates` | read | `campaigns:read` | Get Brand Kit Templates |
+| [`getHomepageSections`](#op-gethomepagesections) | `GET /api/v1/brand-kit/sections` | read | `campaigns:read` | Get Homepage Sections |
+| [`getLayoutSelections`](#op-getlayoutselections) | `GET /api/v1/brand-kit/layout-selections` | read | `campaigns:read` | Get Layout Selections |
+| [`getLayoutTemplatesStatus`](#op-getlayouttemplatesstatus) | `GET /api/v1/brand-kit/layout-templates/status` | read | `campaigns:read` | Get Layout Templates Status |
+| [`getNewsletterSelections`](#op-getnewsletterselections) | `GET /api/v1/brand-kit/newsletter-selections` | read | `campaigns:read` | Get Newsletter Selections |
+| [`getNewsletterTemplatesStatus`](#op-getnewslettertemplatesstatus) | `GET /api/v1/brand-kit/newsletter-templates/status` | read | `campaigns:read` | Get Newsletter Templates Status |
+| [`getSectionLibrary`](#op-getsectionlibrary) | `GET /api/v1/brand-kit/section-library` | read | `campaigns:read` | Get Section Library |
+| [`getSectionLibraryItem`](#op-getsectionlibraryitem) | `GET /api/v1/brand-kit/section-library/{section_id}` | read | `campaigns:read` | Get Section Library Item |
+| [`getSectionTagOverrides`](#op-getsectiontagoverrides) | `GET /api/v1/brand-kit/section-tag-overrides` | read | `campaigns:read` | Get Section Tag Overrides |
+| [`getTemplateGenerationStatus`](#op-gettemplategenerationstatus) | `GET /api/v1/brand-kit/templates/status` | read | `campaigns:read` | Get Template Generation Status |
+| [`improveCustomTemplateIdea`](#op-improvecustomtemplateidea) | `POST /api/v1/brand-kit/layout-templates/improve-idea` | write | `campaigns:write` | Improve Custom Template Idea |
+| [`listArchetypes`](#op-listarchetypes) | `GET /api/v1/brand-kit/archetypes` | read | `campaigns:read` | List Archetypes |
+| [`listCandidatePagesForSectionLibrary`](#op-listcandidatepagesforsectionlibrary) | `GET /api/v1/brand-kit/section-library/candidate-pages` | read | `campaigns:read` | List Candidate Pages For Section Library |
+| [`listCustomLayoutTemplates`](#op-listcustomlayouttemplates) | `GET /api/v1/brand-kit/layout-templates/custom` | read | `campaigns:read` | List Custom Layout Templates |
+| [`listNewsletterArchetypes`](#op-listnewsletterarchetypes) | `GET /api/v1/brand-kit/newsletter-archetypes` | read | `campaigns:read` | List Newsletter Archetypes |
+| [`listNewsletterTemplates`](#op-listnewslettertemplates) | `GET /api/v1/brand-kit/newsletter-templates` | read | `campaigns:read` | List Newsletter Templates |
+| [`planCustomTemplate`](#op-plancustomtemplate) | `POST /api/v1/brand-kit/layout-templates/custom/plan` | write | `campaigns:write` | Plan Custom Template |
+| [`rebuildSectionLibrary`](#op-rebuildsectionlibrary) | `POST /api/v1/brand-kit/section-library/rebuild` | write | `campaigns:write` | Rebuild Section Library |
+| [`recaptureHomepageHtml`](#op-recapturehomepagehtml) | `POST /api/v1/brand-kit/homepage/recapture` | write | `campaigns:write` | Recapture Homepage Html |
+| [`regenerateCustomLayoutTemplate`](#op-regeneratecustomlayouttemplate) | `POST /api/v1/brand-kit/layout-templates/custom/{landing_page_id}/regenerate` | write | `campaigns:write` | Regenerate Custom Layout Template |
+| [`regenerateLayoutTemplates`](#op-regeneratelayouttemplates) | `POST /api/v1/brand-kit/layout-templates/regenerate` | write | `campaigns:write` | Regenerate Layout Templates |
+| [`regenerateNewsletterTemplates`](#op-regeneratenewslettertemplates) | `POST /api/v1/brand-kit/newsletter-templates/regenerate` | write | `campaigns:write` | Regenerate Newsletter Templates |
+| [`saveLayoutSelections`](#op-savelayoutselections) | `PUT /api/v1/brand-kit/layout-selections` | write | `campaigns:write` | Save Layout Selections |
+| [`saveNewsletterSelections`](#op-savenewsletterselections) | `PUT /api/v1/brand-kit/newsletter-selections` | write | `campaigns:write` | Save Newsletter Selections |
+| [`saveSectionTagOverrides`](#op-savesectiontagoverrides) | `PUT /api/v1/brand-kit/section-tag-overrides` | write | `campaigns:write` | Save Section Tag Overrides |
+| [`triggerBrandExtraction`](#op-triggerbrandextraction) | `POST /api/v1/brand-kit/extract` | write | `campaigns:write` | Trigger Brand Extraction |
+
+---
+
+<a id="op-createcustomlayouttemplate"></a>
+
+### `g8.api.brandKit.createCustomLayoutTemplate(input)`
+
+**Create Custom Layout Template**
+
+- HTTP: `POST /api/v1/brand-kit/layout-templates/custom`
+- operationId: `create_custom_layout_template_brand_kit_layout_templates_custom_post` (also callable as `g8.api.call("create_custom_layout_template_brand_kit_layout_templates_custom_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Queue one landing page template built from a plain-language idea.
+
+Pass the `plan` returned by `/layout-templates/custom/plan` to build the
+page you previewed; omit it and the idea is re-interpreted from scratch,
+which will not match the preview.
+
+`attached_assets` are MANDATORY inclusions, not suggestions - the generated
+page uses them. Capped at 5 images and 2 videos.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CustomLayoutTemplateRequest` | yes | Request body; fields below. |
+
+Body fields (`CustomLayoutTemplateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.idea` | `string` | yes | Plain-language description of the page to build. |
+| `body.attached_assets` | `Array<AttachedAsset>` | no | Images and videos the page must use. Max 5 images and 2 videos. |
+| `body.name` | `string \| null` | no | Short title. Derived from the idea when omitted. |
+| `body.plan` | `LpPlan \| null` | no | An approved plan from the plan-preview step. |
+
+**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.brandKit.createCustomLayoutTemplate({ body: { idea: "example" } });
+```
+
+---
+
+<a id="op-deletebrandkittemplates"></a>
+
+### `g8.api.brandKit.deleteBrandKitTemplates(input?)`
+
+**Delete Brand Kit Templates**
+
+- HTTP: `DELETE /api/v1/brand-kit/templates`
+- operationId: `delete_brand_kit_templates_brand_kit_templates_delete` (also callable as `g8.api.call("delete_brand_kit_templates_brand_kit_templates_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `campaigns:delete`
+
+Delete org-level templates so they can be regenerated.
+
+OMITTING `source` DELETES BOTH KINDS. Not reversible, and a campaign built
+on a deleted template keeps its own copy - this removes the org-level
+original, not the pages already made from it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.source` | `string \| null` | no | `layout_archetype` for templates built from a chosen archetype, `homepage` for the one cloned from the org's own site. Omit for both. |
+
+**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.brandKit.deleteBrandKitTemplates();
+```
+
+---
+
+<a id="op-getbrandkithomepage"></a>
+
+### `g8.api.brandKit.getBrandKitHomepage(input?)`
+
+**Get Brand Kit Homepage**
+
+- HTTP: `GET /api/v1/brand-kit/homepage`
+- operationId: `get_brand_kit_homepage_brand_kit_homepage_get` (also callable as `g8.api.call("get_brand_kit_homepage_brand_kit_homepage_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The cloned homepage HTML captured during brand extraction.
+
+This is the raw source everything else here is derived from. It can be
+large - a real homepage with inlined CSS - so prefer `/brand-kit/sections`
+when you want the structure rather than the bytes.
+
+**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.brandKit.getBrandKitHomepage();
+```
+
+---
+
+<a id="op-getbrandkitoverview"></a>
+
+### `g8.api.brandKit.getBrandKitOverview(input?)`
+
+**Get Brand Kit Overview**
+
+- HTTP: `GET /api/v1/brand-kit`
+- operationId: `get_brand_kit_overview_brand_kit_get` (also callable as `g8.api.call("get_brand_kit_overview_brand_kit_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Everything the Brand Kit knows about this organisation, in one read.
+
+Design tokens, the measured colour palette, fonts, whether a homepage has
+been captured and whether templates have been built. The orientation call:
+read this first to find out which of the other routes there is any point
+calling.
+
+**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.brandKit.getBrandKitOverview();
+```
+
+---
+
+<a id="op-getbrandkittemplates"></a>
+
+### `g8.api.brandKit.getBrandKitTemplates(input?)`
+
+**Get Brand Kit Templates**
+
+- HTTP: `GET /api/v1/brand-kit/templates`
+- operationId: `get_brand_kit_templates_brand_kit_templates_get` (also callable as `g8.api.call("get_brand_kit_templates_brand_kit_templates_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The org-level landing page templates a campaign can be built on.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.source` | `string \| null` | no | `layout_archetype` for templates built from a chosen archetype, `homepage` for the one cloned from the org's own site. Omit for both. |
+
+**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.brandKit.getBrandKitTemplates();
+```
+
+---
+
+<a id="op-gethomepagesections"></a>
+
+### `g8.api.brandKit.getHomepageSections(input?)`
+
+**Get Homepage Sections**
+
+- HTTP: `GET /api/v1/brand-kit/sections`
+- operationId: `get_homepage_sections_brand_kit_sections_get` (also callable as `g8.api.call("get_homepage_sections_brand_kit_sections_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The homepage broken into its visual sections.
+
+Derived live from the stored capture, so it changes when the capture does
+and nothing needs rebuilding. The durable, multi-page version is
+`/brand-kit/section-library`.
+
+**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.brandKit.getHomepageSections();
+```
+
+---
+
+<a id="op-getlayoutselections"></a>
+
+### `g8.api.brandKit.getLayoutSelections(input?)`
+
+**Get Layout Selections**
+
+- HTTP: `GET /api/v1/brand-kit/layout-selections`
+- operationId: `get_layout_selections_brand_kit_layout_selections_get` (also callable as `g8.api.call("get_layout_selections_brand_kit_layout_selections_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Which layout archetypes this organisation has chosen.
+
+**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.brandKit.getLayoutSelections();
+```
+
+---
+
+<a id="op-getlayouttemplatesstatus"></a>
+
+### `g8.api.brandKit.getLayoutTemplatesStatus(input?)`
+
+**Get Layout Templates Status**
+
+- HTTP: `GET /api/v1/brand-kit/layout-templates/status`
+- operationId: `get_layout_templates_status_brand_kit_layout_templates_status_get` (also callable as `g8.api.call("get_layout_templates_status_brand_kit_layout_templates_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Per-archetype template build progress.
+
+**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.brandKit.getLayoutTemplatesStatus();
+```
+
+---
+
+<a id="op-getnewsletterselections"></a>
+
+### `g8.api.brandKit.getNewsletterSelections(input?)`
+
+**Get Newsletter Selections**
+
+- HTTP: `GET /api/v1/brand-kit/newsletter-selections`
+- operationId: `get_newsletter_selections_brand_kit_newsletter_selections_get` (also callable as `g8.api.call("get_newsletter_selections_brand_kit_newsletter_selections_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Which newsletter archetypes this organisation has chosen.
+
+**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.brandKit.getNewsletterSelections();
+```
+
+---
+
+<a id="op-getnewslettertemplatesstatus"></a>
+
+### `g8.api.brandKit.getNewsletterTemplatesStatus(input?)`
+
+**Get Newsletter Templates Status**
+
+- HTTP: `GET /api/v1/brand-kit/newsletter-templates/status`
+- operationId: `get_newsletter_templates_status_brand_kit_newsletter_templates_status_get` (also callable as `g8.api.call("get_newsletter_templates_status_brand_kit_newsletter_templates_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Per-archetype newsletter template build progress.
+
+**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.brandKit.getNewsletterTemplatesStatus();
+```
+
+---
+
+<a id="op-getsectionlibrary"></a>
+
+### `g8.api.brandKit.getSectionLibrary(input?)`
+
+**Get Section Library**
+
+- HTTP: `GET /api/v1/brand-kit/section-library`
+- operationId: `get_section_library_brand_kit_section_library_get` (also callable as `g8.api.call("get_section_library_brand_kit_section_library_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Every section in the org's library, across all crawled pages.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.include_code` | `boolean` | no | Include each section's full HTML and CSS. Off by default because the response is an order of magnitude larger with it on - use the detail route for a single preview, and this only for a bulk export. default `false` |
+
+**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.brandKit.getSectionLibrary();
+```
+
+---
+
+<a id="op-getsectionlibraryitem"></a>
+
+### `g8.api.brandKit.getSectionLibraryItem(input)`
+
+**Get Section Library Item**
+
+- HTTP: `GET /api/v1/brand-kit/section-library/{section_id}`
+- operationId: `get_section_library_item_brand_kit_section_library__section_id__get` (also callable as `g8.api.call("get_section_library_item_brand_kit_section_library__section_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+One section, with self-contained HTML ready to render in an iframe.
+
+Self-contained means the CSS travels with it - this is the preview call,
+and the reason `include_code` is off on the list route.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.section_id` | `string` | yes | Section 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.brandKit.getSectionLibraryItem({ path: { section_id: "id" } });
+```
+
+---
+
+<a id="op-getsectiontagoverrides"></a>
+
+### `g8.api.brandKit.getSectionTagOverrides(input?)`
+
+**Get Section Tag Overrides**
+
+- HTTP: `GET /api/v1/brand-kit/section-tag-overrides`
+- operationId: `get_section_tag_overrides_brand_kit_section_tag_overrides_get` (also callable as `g8.api.call("get_section_tag_overrides_brand_kit_section_tag_overrides_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Durable per-section tag and category overrides.
+
+Tags are derived automatically; these are the corrections that survive a
+rebuild. Without them, every rebuild re-derives the same wrong tag.
+
+**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.brandKit.getSectionTagOverrides();
+```
+
+---
+
+<a id="op-gettemplategenerationstatus"></a>
+
+### `g8.api.brandKit.getTemplateGenerationStatus(input?)`
+
+**Get Template Generation Status**
+
+- HTTP: `GET /api/v1/brand-kit/templates/status`
+- operationId: `get_template_generation_status_brand_kit_templates_status_get` (also callable as `g8.api.call("get_template_generation_status_brand_kit_templates_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+Whether template generation is running, finished or failed.
+
+**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.brandKit.getTemplateGenerationStatus();
+```
+
+---
+
+<a id="op-improvecustomtemplateidea"></a>
+
+### `g8.api.brandKit.improveCustomTemplateIdea(input)`
+
+**Improve Custom Template Idea**
+
+- HTTP: `POST /api/v1/brand-kit/layout-templates/improve-idea`
+- operationId: `improve_custom_template_idea_brand_kit_layout_templates_improve_idea_post` (also callable as `g8.api.call("improve_custom_template_idea_brand_kit_layout_templates_improve_idea_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Rewrite a one-line idea into a fuller brief. Changes nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ImproveIdeaRequest` | yes | Request body; fields below. |
+
+Body fields (`ImproveIdeaRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.idea` | `string` | yes | The raw idea to rewrite into a fuller brief. |
+
+**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.brandKit.improveCustomTemplateIdea({ body: { idea: "example" } });
+```
+
+---
+
+<a id="op-listarchetypes"></a>
+
+### `g8.api.brandKit.listArchetypes(input?)`
+
+**List Archetypes**
+
+- HTTP: `GET /api/v1/brand-kit/archetypes`
+- operationId: `list_archetypes_brand_kit_archetypes_get` (also callable as `g8.api.call("list_archetypes_brand_kit_archetypes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The catalogue of landing page layout archetypes.
+
+GLOBAL, not per-organisation: the same catalogue for everyone. Your org's
+picks from it are `/brand-kit/layout-selections`.
+
+**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.brandKit.listArchetypes();
+```
+
+---
+
+<a id="op-listcandidatepagesforsectionlibrary"></a>
+
+### `g8.api.brandKit.listCandidatePagesForSectionLibrary(input?)`
+
+**List Candidate Pages For Section Library**
+
+- HTTP: `GET /api/v1/brand-kit/section-library/candidate-pages`
+- operationId: `list_candidate_pages_for_section_library_brand_kit_section_library_candidate_pages_get` (also callable as `g8.api.call("list_candidate_pages_for_section_library_brand_kit_section_library_candidate_pages_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The pages a rebuild could draw sections from.
+
+Declared BEFORE `/section-library/{section_id}`. The app declares them the
+other way round, so in the app this path is matched by the detail route and
+resolves a section id of "candidate-pages" instead. Read this to choose
+`page_urls` for a rebuild.
+
+**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.brandKit.listCandidatePagesForSectionLibrary();
+```
+
+---
+
+<a id="op-listcustomlayouttemplates"></a>
+
+### `g8.api.brandKit.listCustomLayoutTemplates(input?)`
+
+**List Custom Layout Templates**
+
+- HTTP: `GET /api/v1/brand-kit/layout-templates/custom`
+- operationId: `list_custom_layout_templates_brand_kit_layout_templates_custom_get` (also callable as `g8.api.call("list_custom_layout_templates_brand_kit_layout_templates_custom_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The idea-driven templates already built for this organisation.
+
+**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.brandKit.listCustomLayoutTemplates();
+```
+
+---
+
+<a id="op-listnewsletterarchetypes"></a>
+
+### `g8.api.brandKit.listNewsletterArchetypes(input?)`
+
+**List Newsletter Archetypes**
+
+- HTTP: `GET /api/v1/brand-kit/newsletter-archetypes`
+- operationId: `list_newsletter_archetypes_brand_kit_newsletter_archetypes_get` (also callable as `g8.api.call("list_newsletter_archetypes_brand_kit_newsletter_archetypes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The catalogue of newsletter archetypes. GLOBAL, not per-organisation.
+
+**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.brandKit.listNewsletterArchetypes();
+```
+
+---
+
+<a id="op-listnewslettertemplates"></a>
+
+### `g8.api.brandKit.listNewsletterTemplates(input?)`
+
+**List Newsletter Templates**
+
+- HTTP: `GET /api/v1/brand-kit/newsletter-templates`
+- operationId: `list_newsletter_templates_brand_kit_newsletter_templates_get` (also callable as `g8.api.call("list_newsletter_templates_brand_kit_newsletter_templates_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `campaigns:read`
+
+The newsletter templates built from this org's Brand Kit picks.
+
+**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.brandKit.listNewsletterTemplates();
+```
+
+---
+
+<a id="op-plancustomtemplate"></a>
+
+### `g8.api.brandKit.planCustomTemplate(input)`
+
+**Plan Custom Template**
+
+- HTTP: `POST /api/v1/brand-kit/layout-templates/custom/plan`
+- operationId: `plan_custom_template_brand_kit_layout_templates_custom_plan_post` (also callable as `g8.api.call("plan_custom_template_brand_kit_layout_templates_custom_plan_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Preview the section plan for an idea. Builds nothing, stores nothing.
+
+The review step: it returns the plan a build WOULD follow, so the plan can
+be edited and handed back to `POST /layout-templates/custom` instead of
+discovering the interpretation was wrong after the page exists.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CustomTemplatePlanRequest` | yes | Request body; fields below. |
+
+Body fields (`CustomTemplatePlanRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.idea` | `string` | yes | Plain-language description of the page to plan. |
+| `body.attached_assets` | `Array<AttachedAsset>` | no | Images and videos the plan must place. |
+| `body.name` | `string \| null` | no | Short title. |
+
+**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.brandKit.planCustomTemplate({ body: { idea: "example" } });
+```
+
+---
+
+<a id="op-rebuildsectionlibrary"></a>
+
+### `g8.api.brandKit.rebuildSectionLibrary(input?)`
+
+**Rebuild Section Library**
+
+- HTTP: `POST /api/v1/brand-kit/section-library/rebuild`
+- operationId: `rebuild_section_library_brand_kit_section_library_rebuild_post` (also callable as `g8.api.call("rebuild_section_library_brand_kit_section_library_rebuild_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Rebuild the section library. REPLACES what is there.
+
+The two overrides are not interchangeable: `page_urls` REPLACES the
+automatic page selection, `extra_page_urls` ADDS to it. Send neither to let
+the picker choose. Asynchronous.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SectionLibraryRebuildRequest \| null` | no | Request body; fields below. |
+
+Body fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.extra_page_urls` | `Array<string> \| null` | no | Add these pages to whatever the picker chose. |
+| `body.page_urls` | `Array<string> \| null` | no | Replace the automatic page selection with exactly these pages. |
+
+**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.brandKit.rebuildSectionLibrary();
+```
+
+---
+
+<a id="op-recapturehomepagehtml"></a>
+
+### `g8.api.brandKit.recaptureHomepageHtml(input?)`
+
+**Recapture Homepage Html**
+
+- HTTP: `POST /api/v1/brand-kit/homepage/recapture`
+- operationId: `recapture_homepage_html_brand_kit_homepage_recapture_post` (also callable as `g8.api.call("recapture_homepage_html_brand_kit_homepage_recapture_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Re-capture the homepage for full CSS fidelity.
+
+REPLACES the stored capture. Reaches an external scraping provider, so it
+is slower and costlier than anything else here - run it when the customer's
+site has actually changed, not as a refresh.
+
+**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.brandKit.recaptureHomepageHtml();
+```
+
+---
+
+<a id="op-regeneratecustomlayouttemplate"></a>
+
+### `g8.api.brandKit.regenerateCustomLayoutTemplate(input)`
+
+**Regenerate Custom Layout Template**
+
+- HTTP: `POST /api/v1/brand-kit/layout-templates/custom/{landing_page_id}/regenerate`
+- operationId: `regenerate_custom_layout_template_brand_kit_layout_templates_custom__landing_page_id__regenerate_post` (also callable as `g8.api.call("regenerate_custom_layout_template_brand_kit_layout_templates_custom__landing_page_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`
+
+Re-run a custom build with the same idea. REPLACES the template.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.landing_page_id` | `string` | yes | The custom template to rebuild. |
+| `query.clear_plan` | `boolean` | no | Discard the stored plan and re-derive one from the original idea. Leave false to rebuild against the plan that was approved. default `false` |
+
+**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.brandKit.regenerateCustomLayoutTemplate({ path: { landing_page_id: "id" } });
+```
+
+---
+
+<a id="op-regeneratelayouttemplates"></a>
+
+### `g8.api.brandKit.regenerateLayoutTemplates(input?)`
+
+**Regenerate Layout Templates**
+
+- HTTP: `POST /api/v1/brand-kit/layout-templates/regenerate`
+- operationId: `regenerate_layout_templates_brand_kit_layout_templates_regenerate_post` (also callable as `g8.api.call("regenerate_layout_templates_brand_kit_layout_templates_regenerate_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Build the landing page templates for the selected archetypes.
+
+Asynchronous. Poll `GET /brand-kit/layout-templates/status` for per-archetype
+progress.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.archetype_id` | `string \| null` | no | Rebuild ONE archetype's template. Omit to run the layout picker and rebuild every selected archetype - which is much more work. |
+
+**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.brandKit.regenerateLayoutTemplates();
+```
+
+---
+
+<a id="op-regeneratenewslettertemplates"></a>
+
+### `g8.api.brandKit.regenerateNewsletterTemplates(input?)`
+
+**Regenerate Newsletter Templates**
+
+- HTTP: `POST /api/v1/brand-kit/newsletter-templates/regenerate`
+- operationId: `regenerate_newsletter_templates_brand_kit_newsletter_templates_regenerate_post` (also callable as `g8.api.call("regenerate_newsletter_templates_brand_kit_newsletter_templates_regenerate_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Build newsletter templates for the selected archetypes. Asynchronous.
+
+**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.brandKit.regenerateNewsletterTemplates();
+```
+
+---
+
+<a id="op-savelayoutselections"></a>
+
+### `g8.api.brandKit.saveLayoutSelections(input)`
+
+**Save Layout Selections**
+
+- HTTP: `PUT /api/v1/brand-kit/layout-selections`
+- operationId: `save_layout_selections_brand_kit_layout_selections_put` (also callable as `g8.api.call("save_layout_selections_brand_kit_layout_selections_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+REPLACE the org's layout archetype selection.
+
+Selecting is not building: the templates are produced by
+`POST /brand-kit/layout-templates/regenerate` afterwards.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `LayoutSelectionRequest` | yes | Request body; fields below. |
+
+Body fields (`LayoutSelectionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.archetype_ids` | `Array<string>` | yes | The complete set of selected layout archetype ids. |
+
+**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.brandKit.saveLayoutSelections({ body: { archetype_ids: ["id"] } });
+```
+
+---
+
+<a id="op-savenewsletterselections"></a>
+
+### `g8.api.brandKit.saveNewsletterSelections(input)`
+
+**Save Newsletter Selections**
+
+- HTTP: `PUT /api/v1/brand-kit/newsletter-selections`
+- operationId: `save_newsletter_selections_brand_kit_newsletter_selections_put` (also callable as `g8.api.call("save_newsletter_selections_brand_kit_newsletter_selections_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+REPLACE the org's newsletter archetype selection.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `NewsletterSelectionsRequest` | yes | Request body; fields below. |
+
+Body fields (`NewsletterSelectionsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.archetype_ids` | `Array<string>` | yes | The complete set of selected newsletter archetype ids. |
+
+**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.brandKit.saveNewsletterSelections({ body: { archetype_ids: ["id"] } });
+```
+
+---
+
+<a id="op-savesectiontagoverrides"></a>
+
+### `g8.api.brandKit.saveSectionTagOverrides(input)`
+
+**Save Section Tag Overrides**
+
+- HTTP: `PUT /api/v1/brand-kit/section-tag-overrides`
+- operationId: `save_section_tag_overrides_brand_kit_section_tag_overrides_put` (also callable as `g8.api.call("save_section_tag_overrides_brand_kit_section_tag_overrides_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Upsert tag overrides, keyed by section id.
+
+UPSERT, not replace: sections you do not mention keep the overrides they
+already had. To clear one, send it with empty lists.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SectionTagOverridesRequest` | yes | Request body; fields below. |
+
+Body fields (`SectionTagOverridesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.overrides` | `Record<string, SectionTagOverride>` | no | Section id -> tag override. |
+
+**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.brandKit.saveSectionTagOverrides({ body: {} });
+```
+
+---
+
+<a id="op-triggerbrandextraction"></a>
+
+### `g8.api.brandKit.triggerBrandExtraction(input?)`
+
+**Trigger Brand Extraction**
+
+- HTTP: `POST /api/v1/brand-kit/extract`
+- operationId: `trigger_brand_extraction_brand_kit_extract_post` (also callable as `g8.api.call("trigger_brand_extraction_brand_kit_extract_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `campaigns:write`
+
+Start, or restart, brand extraction.
+
+Omit the body to re-extract the website already on the org's company
+profile. Supplying `website_url` EXTRACTS A DIFFERENT SITE and replaces
+the org's design tokens and homepage capture with that site's - which is
+how a brand kit ends up belonging to the wrong company. Asynchronous; the
+result appears on `GET /brand-kit`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `BrandExtractionRequest \| null` | no | Request body; fields below. |
+
+Body fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.website_url` | `string \| null` | no | Site to extract from. Omit to re-extract the org's current website. |
+
+**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.brandKit.triggerBrandExtraction();
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-attachedasset"></a>
+
+### `AttachedAsset`
+
+Mirrors `campaign_builder.routers.brand_kit.AttachedAsset`. An asset the generated page MUST use. Capped by the app at 5 images and 2 videos per submission; the cap is a model validator there, so it answers 422 through the same path as any other body error.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes | Asset id. |
+| `type` | `"image" \| "video"` | yes | Asset kind. |
+| `url` | `string` | yes | Public URL the generated page will reference. |
+| `alt_text` | `string \| null` | no | Alt text. |
+| `position_hint` | `"hero" \| "body" \| "any"` | no | Where the asset should land on the page. default `"any"` |
+| `poster_url` | `string \| null` | no | Poster frame for a video. |
+| `title` | `string \| null` | no | Title. |
+
+<a id="type-lpplan"></a>
+
+### `LpPlan`
+
+Full landing-page plan — 1..8 sections.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `sections` | `Array<PlanSection>` | yes | min items 1, max items 8 |
+
+<a id="type-sectiontagoverride"></a>
+
+### `SectionTagOverride`
+
+Mirrors `campaign_builder.routers.brand_kit.SectionTagOverride`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `category` | `string \| null` | no | Category override for this section. |
+| `custom` | `Array<string>` | no | Tags added to this section. |
+| `hidden` | `Array<string>` | no | Auto-derived tags suppressed for this section. |