@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/adCampaigns.md

@@ -0,0 +1,1091 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.adCampaigns`: Ad Campaigns
+
+19 operations (6 read, 2 destructive, 11 external).
+
+No hand-written client covers this area. Call it through `g8.api.adCampaigns.*` 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: [adCampaigns.d.ts](adCampaigns.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`archiveCampaignAd`](#op-archivecampaignad) | `DELETE /api/v1/ad-campaigns/{campaign_id}/ads/{ad_id}` | destructive | `ads:delete` | Archive Campaign Ad |
+| [`createCampaignAd`](#op-createcampaignad) | `POST /api/v1/ad-campaigns/{campaign_id}/ads` | external | `ads:run` | Create Campaign Ad |
+| [`createCampaignAdsBatch`](#op-createcampaignadsbatch) | `POST /api/v1/ad-campaigns/{campaign_id}/ads/batch` | external | `ads:run` | Create Campaign Ads Batch |
+| [`deleteAdCampaign`](#op-deleteadcampaign) | `DELETE /api/v1/ad-campaigns/{campaign_id}` | destructive | `ads:delete` | Delete Ad Campaign |
+| [`getAdCampaign`](#op-getadcampaign) | `GET /api/v1/ad-campaigns/{campaign_id}` | read | `ads:read` | Get Ad Campaign |
+| [`getCampaignAd`](#op-getcampaignad) | `GET /api/v1/ad-campaigns/{campaign_id}/ads/{ad_id}` | read | `ads:read` | Get Campaign Ad |
+| [`getCampaignEditableFields`](#op-getcampaigneditablefields) | `GET /api/v1/ad-campaigns/{campaign_id}/editable` | read | `ads:read` | Get Campaign Editable Fields |
+| [`getPerCampaignMetrics`](#op-getpercampaignmetrics) | `GET /api/v1/ad-campaigns/metrics` | read | `ads:read` | Get Per Campaign Metrics |
+| [`launchAdCampaign`](#op-launchadcampaign) | `POST /api/v1/audience-syncs/{config_id}/launch` | external | `ads:run` | Launch Ad Campaign |
+| [`listAdCampaigns`](#op-listadcampaigns) | `GET /api/v1/ad-campaigns` | read | `ads:read` | List Ad Campaigns |
+| [`listCampaignAds`](#op-listcampaignads) | `GET /api/v1/ad-campaigns/{campaign_id}/ads` | read | `ads:read` | List Campaign Ads |
+| [`previewAdCampaignEdit`](#op-previewadcampaignedit) | `POST /api/v1/ad-campaigns/{campaign_id}/edit-preview` | external | `ads:run` | Preview Ad Campaign Edit |
+| [`refreshAllCampaignStatuses`](#op-refreshallcampaignstatuses) | `POST /api/v1/ad-campaigns/status-refresh` | external | `ads:run` | Refresh All Campaign Statuses |
+| [`refreshCampaignStatus`](#op-refreshcampaignstatus) | `POST /api/v1/ad-campaigns/{campaign_id}/status-refresh` | external | `ads:run` | Refresh Campaign Status |
+| [`retryCampaignLaunch`](#op-retrycampaignlaunch) | `POST /api/v1/ad-campaigns/{campaign_id}/retry` | external | `ads:run` | Retry Campaign Launch |
+| [`setCampaignAdStatus`](#op-setcampaignadstatus) | `POST /api/v1/ad-campaigns/{campaign_id}/ads/{ad_id}/status` | external | `ads:run` | Set Campaign Ad Status |
+| [`updateAdCampaign`](#op-updateadcampaign) | `PUT /api/v1/ad-campaigns/{campaign_id}` | external | `ads:run` | Update Ad Campaign |
+| [`updateCampaignAd`](#op-updatecampaignad) | `PATCH /api/v1/ad-campaigns/{campaign_id}/ads/{ad_id}` | external | `ads:run` | Update Campaign Ad |
+| [`uploadAdImage`](#op-uploadadimage) | `POST /api/v1/ad-campaigns/images` | external | `ads:run` | Upload Ad Image |
+
+---
+
+<a id="op-archivecampaignad"></a>
+
+### `g8.api.adCampaigns.archiveCampaignAd(input)`
+
+**Archive Campaign Ad**
+
+- HTTP: `DELETE /api/v1/ad-campaigns/{campaign_id}/ads/{ad_id}`
+- operationId: `archive_campaign_ad_ad_campaigns__campaign_id__ads__ad_id__delete` (also callable as `g8.api.call("archive_campaign_ad_ad_campaigns__campaign_id__ads__ad_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `ads:delete`
+
+Permanently stop one ad.
+
+Archive, not hard-delete: Google's remove and LinkedIn's archive are both
+one-way, so the ad is retained with ``status="archived"`` and the spend it
+already incurred stays attributable. Refuses on a campaign's last remaining
+ad — pause or delete the campaign instead of leaving it serving nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `integer` | yes | Ad campaign ID |
+| `path.ad_id` | `integer` | yes | graph8 ad ID |
+
+**Returns** `ApiResponse_AdResponse_`: the envelope `{ data: AdResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AdResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `campaign_id` | `integer` | yes |  |
+| `slot_index` | `integer` | yes |  |
+| `status` | `string` | yes | draft \| launching \| active \| paused \| archived \| failed |
+| `approval_nuance` | `string \| null` | no |  |
+| `copy_assets` | `Record<string, unknown> \| null` | no | Multi-asset copy, e.g. {rsa_headlines: [...], rsa_descriptions: [...]} |
+| `created_at` | `string \| null` | no |  |
+| `creative_image_url` | `string \| null` | no |  |
+| `creative_image_url_portrait` | `string \| null` | no |  |
+| `creative_image_url_square` | `string \| null` | no |  |
+| `cta` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `destination_url` | `string \| null` | no |  |
+| `error_message` | `string \| null` | no |  |
+| `headline` | `string \| null` | no |  |
+| `id` | `integer \| null` | no | graph8 ad id, stable across creative replacements. Null only for a campaign launched before per-ad control, until its first read. |
+| `launched_at` | `string \| null` | no |  |
+| `logo_image_url` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `platform_ad_id` | `string \| null` | no | Current platform handle. Changes when the creative is replaced. |
+| `policy_topics` | `Array<Record<string, unknown>> \| null` | no |  |
+| `primary_text` | `string \| null` | no |  |
+| `source_ad_creative_id` | `string \| null` | no | The Studio creative this ad was built from, when it came from Studio |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.adCampaigns.archiveCampaignAd({ path: { campaign_id: 123, ad_id: 123 } });
+```
+
+---
+
+<a id="op-createcampaignad"></a>
+
+### `g8.api.adCampaigns.createCampaignAd(input)`
+
+**Create Campaign Ad**
+
+- HTTP: `POST /api/v1/ad-campaigns/{campaign_id}/ads`
+- operationId: `create_campaign_ad_ad_campaigns__campaign_id__ads_post` (also callable as `g8.api.call("create_campaign_ad_ad_campaigns__campaign_id__ads_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `ads:run`
+
+Add an ad to a campaign.
+
+On a launched campaign the ad goes live immediately and begins consuming the
+campaign's budget. This spends money, so the key needs ``ads:run``.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `integer` | yes | Ad campaign ID |
+| `body` | `AdCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`AdCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.copy_assets` | `Record<string, unknown> \| null` | no |  |
+| `body.creative_image_url` | `string \| null` | no | max length 500 |
+| `body.creative_image_url_portrait` | `string \| null` | no | max length 500 |
+| `body.creative_image_url_square` | `string \| null` | no | max length 500 |
+| `body.cta` | `string \| null` | no | max length 50 |
+| `body.description` | `string \| null` | no | max length 1000 |
+| `body.destination_url` | `string \| null` | no | max length 500 |
+| `body.headline` | `string \| null` | no | max length 255 |
+| `body.logo_image_url` | `string \| null` | no | max length 500 |
+| `body.name` | `string \| null` | no | max length 255 |
+| `body.primary_text` | `string \| null` | no | max length 1000 |
+| `body.source_ad_creative_id` | `string \| null` | no | max length 64 |
+
+**Returns** `ApiResponse_AdResponse_`: the envelope `{ data: AdResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AdResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `campaign_id` | `integer` | yes |  |
+| `slot_index` | `integer` | yes |  |
+| `status` | `string` | yes | draft \| launching \| active \| paused \| archived \| failed |
+| `approval_nuance` | `string \| null` | no |  |
+| `copy_assets` | `Record<string, unknown> \| null` | no | Multi-asset copy, e.g. {rsa_headlines: [...], rsa_descriptions: [...]} |
+| `created_at` | `string \| null` | no |  |
+| `creative_image_url` | `string \| null` | no |  |
+| `creative_image_url_portrait` | `string \| null` | no |  |
+| `creative_image_url_square` | `string \| null` | no |  |
+| `cta` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `destination_url` | `string \| null` | no |  |
+| `error_message` | `string \| null` | no |  |
+| `headline` | `string \| null` | no |  |
+| `id` | `integer \| null` | no | graph8 ad id, stable across creative replacements. Null only for a campaign launched before per-ad control, until its first read. |
+| `launched_at` | `string \| null` | no |  |
+| `logo_image_url` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `platform_ad_id` | `string \| null` | no | Current platform handle. Changes when the creative is replaced. |
+| `policy_topics` | `Array<Record<string, unknown>> \| null` | no |  |
+| `primary_text` | `string \| null` | no |  |
+| `source_ad_creative_id` | `string \| null` | no | The Studio creative this ad was built from, when it came from Studio |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.adCampaigns.createCampaignAd({ path: { campaign_id: 123 }, body: {} });
+```
+
+---
+
+<a id="op-createcampaignadsbatch"></a>
+
+### `g8.api.adCampaigns.createCampaignAdsBatch(input)`
+
+**Create Campaign Ads Batch**
+
+- HTTP: `POST /api/v1/ad-campaigns/{campaign_id}/ads/batch`
+- operationId: `create_campaign_ads_batch_ad_campaigns__campaign_id__ads_batch_post` (also callable as `g8.api.call("create_campaign_ads_batch_ad_campaigns__campaign_id__ads_batch_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `ads:run`
+
+Add several ads at once.
+
+Returns ``status="partial"`` when any individual ad failed, with per-ad
+outcomes in ``results``. Inspect those rather than treating a 200 as total
+success — one creative rejected on policy does not stop its siblings.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `integer` | yes | Ad campaign ID |
+| `body` | `AdBatchCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`AdBatchCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.ads` | `Array<AdCreateRequest>` | yes | min items 1, max items 20 |
+
+**Returns** `ApiResponse_AdBatchCreateResponse_`: the envelope `{ data: AdBatchCreateResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AdBatchCreateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `campaign_id` | `integer` | yes |  |
+| `failed` | `integer` | yes |  |
+| `requested` | `integer` | yes |  |
+| `results` | `Array<AdBatchResultItem>` | yes |  |
+| `status` | `string` | yes | ok \| partial — never render success off a 200 alone |
+| `succeeded` | `integer` | yes |  |
+| `platform` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.adCampaigns.createCampaignAdsBatch({ path: { campaign_id: 123 }, body: { ads: [{}] } });
+```
+
+---
+
+<a id="op-deleteadcampaign"></a>
+
+### `g8.api.adCampaigns.deleteAdCampaign(input)`
+
+**Delete Ad Campaign**
+
+- HTTP: `DELETE /api/v1/ad-campaigns/{campaign_id}`
+- operationId: `delete_ad_campaign_ad_campaigns__campaign_id__delete` (also callable as `g8.api.call("delete_ad_campaign_ad_campaigns__campaign_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `ads:delete`
+
+Stop and remove a campaign.
+
+THIS STOPS A LIVE CAMPAIGN ON THE PLATFORM FIRST, then removes graph8's
+row. There is no undo: the platform-side removal is the platform's, and the
+campaign's history goes with the local row.
+
+502 - not 404 - when the platform refuses the removal, because the campaign
+is then still LIVE AND SPENDING and reporting success would be the worst
+possible answer.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `integer` | yes | The ad campaign's id. |
+
+**Returns** `ApiResponse_AdPayload_`: the envelope `{ data: AdPayload, ... }`. `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.adCampaigns.deleteAdCampaign({ path: { campaign_id: 123 } });
+```
+
+---
+
+<a id="op-getadcampaign"></a>
+
+### `g8.api.adCampaigns.getAdCampaign(input)`
+
+**Get Ad Campaign**
+
+- HTTP: `GET /api/v1/ad-campaigns/{campaign_id}`
+- operationId: `get_ad_campaign_ad_campaigns__campaign_id__get` (also callable as `g8.api.call("get_ad_campaign_ad_campaigns__campaign_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `ads:read`
+
+Fetch one paid ad campaign.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `integer` | yes | Ad campaign ID |
+
+**Returns** `ApiResponse_AdCampaignResponse_`: the envelope `{ data: AdCampaignResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AdCampaignResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `integer` | yes |  |
+| `name` | `string` | yes |  |
+| `platform` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `sync_config_id` | `integer` | yes |  |
+| `ad_count` | `integer` | no | Number of live (non-archived) ads in this campaign default `0` |
+| `created_at` | `string \| null` | no |  |
+| `currency` | `string \| null` | no |  |
+| `daily_budget` | `number \| null` | no |  |
+| `end_date` | `string \| null` | no |  |
+| `google_campaign_subtype` | `string \| null` | no |  |
+| `launched_at` | `string \| null` | no |  |
+| `objective` | `string \| null` | no |  |
+| `platform_campaign_id` | `string \| null` | no |  |
+| `start_date` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.adCampaigns.getAdCampaign({ path: { campaign_id: 123 } });
+```
+
+---
+
+<a id="op-getcampaignad"></a>
+
+### `g8.api.adCampaigns.getCampaignAd(input)`
+
+**Get Campaign Ad**
+
+- HTTP: `GET /api/v1/ad-campaigns/{campaign_id}/ads/{ad_id}`
+- operationId: `get_campaign_ad_ad_campaigns__campaign_id__ads__ad_id__get` (also callable as `g8.api.call("get_campaign_ad_ad_campaigns__campaign_id__ads__ad_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `ads:read`
+
+Fetch one ad.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `integer` | yes | Ad campaign ID |
+| `path.ad_id` | `integer` | yes | graph8 ad ID |
+
+**Returns** `ApiResponse_AdResponse_`: the envelope `{ data: AdResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AdResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `campaign_id` | `integer` | yes |  |
+| `slot_index` | `integer` | yes |  |
+| `status` | `string` | yes | draft \| launching \| active \| paused \| archived \| failed |
+| `approval_nuance` | `string \| null` | no |  |
+| `copy_assets` | `Record<string, unknown> \| null` | no | Multi-asset copy, e.g. {rsa_headlines: [...], rsa_descriptions: [...]} |
+| `created_at` | `string \| null` | no |  |
+| `creative_image_url` | `string \| null` | no |  |
+| `creative_image_url_portrait` | `string \| null` | no |  |
+| `creative_image_url_square` | `string \| null` | no |  |
+| `cta` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `destination_url` | `string \| null` | no |  |
+| `error_message` | `string \| null` | no |  |
+| `headline` | `string \| null` | no |  |
+| `id` | `integer \| null` | no | graph8 ad id, stable across creative replacements. Null only for a campaign launched before per-ad control, until its first read. |
+| `launched_at` | `string \| null` | no |  |
+| `logo_image_url` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `platform_ad_id` | `string \| null` | no | Current platform handle. Changes when the creative is replaced. |
+| `policy_topics` | `Array<Record<string, unknown>> \| null` | no |  |
+| `primary_text` | `string \| null` | no |  |
+| `source_ad_creative_id` | `string \| null` | no | The Studio creative this ad was built from, when it came from Studio |
+
+**Example**
+
+```ts
+const result = await g8.api.adCampaigns.getCampaignAd({ path: { campaign_id: 123, ad_id: 123 } });
+```
+
+---
+
+<a id="op-getcampaigneditablefields"></a>
+
+### `g8.api.adCampaigns.getCampaignEditableFields(input)`
+
+**Get Campaign Editable Fields**
+
+- HTTP: `GET /api/v1/ad-campaigns/{campaign_id}/editable`
+- operationId: `get_campaign_editable_fields_ad_campaigns__campaign_id__editable_get` (also callable as `g8.api.call("get_campaign_editable_fields_ad_campaigns__campaign_id__editable_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `ads:read`
+
+Which of this campaign's fields the platform will actually let you change.
+
+Platform- and state-dependent: a live Google Search campaign accepts a
+budget change and refuses a channel change, and a campaign in review
+accepts almost nothing. Read this before attempting an edit.
+
+Gated on `ads:launch` rather than `ads:view`, as the app gates it: it
+describes the money controls, and the app treats that whole surface as one
+permission.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `integer` | yes | The ad campaign's id. |
+
+**Returns** `ApiResponse_AdPayload_`: the envelope `{ data: AdPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.adCampaigns.getCampaignEditableFields({ path: { campaign_id: 123 } });
+```
+
+---
+
+<a id="op-getpercampaignmetrics"></a>
+
+### `g8.api.adCampaigns.getPerCampaignMetrics(input?)`
+
+**Get Per Campaign Metrics**
+
+- HTTP: `GET /api/v1/ad-campaigns/metrics`
+- operationId: `get_per_campaign_metrics_ad_campaigns_metrics_get` (also callable as `g8.api.call("get_per_campaign_metrics_ad_campaigns_metrics_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `ads:read`
+
+Spend and performance broken down per campaign.
+
+A two-segment LITERAL under a prefix that already has
+`GET /ad-campaigns/{campaign_id}` typed `int`, so this router is included
+first. The app's own router carries a comment about this exact endpoint
+being shadowed once already.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Days to look back. default `30` |
+| `query.platform` | `"meta" \| "linkedin" \| "google" \| "x" \| null` | no | One platform. Omit for all. |
+| `query.ad_account_id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_AdPayload_`: the envelope `{ data: AdPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.adCampaigns.getPerCampaignMetrics();
+```
+
+---
+
+<a id="op-launchadcampaign"></a>
+
+### `g8.api.adCampaigns.launchAdCampaign(input)`
+
+**Launch Ad Campaign**
+
+- HTTP: `POST /api/v1/audience-syncs/{config_id}/launch`
+- operationId: `launch_ad_campaign_audience_syncs__config_id__launch_post` (also callable as `g8.api.call("launch_ad_campaign_audience_syncs__config_id__launch_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `ads:run`
+
+Launch a paid campaign on the platform, targeting this sync's audience.
+
+THIS SPENDS THE CUSTOMER'S ADVERTISING BUDGET. The campaign goes live with
+`daily_budget` in `currency` from `start_date`, and the platform starts
+charging as soon as it serves. `spend_cap` and `auto_pause_at` are the
+guard rails; set them. Upload the creative first with
+`POST /ad-campaigns/images`.
+
+READ `status` IN THE BODY. The app answers a refused launch (campaign not
+found, the platform rejecting it) with a 200 whose `status` is `error`, and
+this route passes that through unchanged rather than guessing an HTTP code
+for it. A launch can also partly succeed - the platform accepts the campaign
+and then rejects a creative in review - so follow up with
+`POST /ad-campaigns/{campaign_id}/status-refresh`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.config_id` | `integer` | yes | The sync config whose audience the campaign targets. |
+| `body` | `LaunchAdCampaignRequest` | yes | Request body; fields below. |
+
+Body fields (`LaunchAdCampaignRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.ad_copy_variant_index` | `integer \| null` | no |  |
+| `body.ad_image_document_id` | `integer \| null` | no |  |
+| `body.auto_pause_at` | `string (date-time) \| null` | no | Absolute UTC instant to auto-pause at (ISO-8601 with offset) |
+| `body.auto_pause_tz` | `string \| null` | no | IANA zone the user picked in (display/intent only) max length 64 |
+| `body.creative_image_url` | `string \| null` | no | default `""`, max length 500 |
+| `body.creative_image_url_portrait` | `string \| null` | no | default `""`, max length 500 |
+| `body.creative_image_url_square` | `string \| null` | no | default `""`, max length 500 |
+| `body.cta` | `string \| null` | no | default `"LEARN_MORE"` |
+| `body.currency` | `string` | no | default `"USD"`, max length 3 |
+| `body.custom_segment_keywords` | `Array<string> \| null` | no | Demand Gen only: intent keywords for a custom segment (people who search these) |
+| `body.custom_segment_urls` | `Array<string> \| null` | no | Demand Gen only: competitor/relevant URLs for a custom segment (people who browse these) |
+| `body.customer_match_mode` | `string \| null` | no | Google Customer Match mode: observation (default) \| targeting \| exclusion default `"observation"` |
+| `body.daily_budget` | `number` | no | default `50`, > 0 |
+| `body.destination_url` | `string \| null` | no | default `""`, max length 500 |
+| `body.end_date` | `string (date) \| null` | no |  |
+| `body.geo_target_country` | `string \| null` | no | ISO 3166-1 alpha-2 country code for the location criterion (Google observation/exclusion modes) default `"US"`, min length 2, max length 2 |
+| `body.google_campaign_subtype` | `string \| null` | no | Google campaign subtype: display (default) \| demand_gen \| search default `"display"` |
+| `body.headline` | `string \| null` | no | default `""`, max length 255 |
+| `body.include_lookalike_audiences` | `boolean \| null` | no | Demand Gen only: attach the lookalike segment derived from the Customer Match list default `false` |
+| `body.logo_image_url` | `string \| null` | no | default `""`, max length 500 |
+| `body.name` | `string \| null` | no | User-provided campaign name; auto-generated if empty default `""`, max length 255 |
+| `body.objective` | `string` | no | default `"traffic"` |
+| `body.primary_text` | `string \| null` | no | default `""`, max length 1000 |
+| `body.rsa_descriptions` | `Array<string> \| null` | no | Google Search only: 2-4 Responsive Search Ad descriptions (≤90 chars each) |
+| `body.rsa_headlines` | `Array<string> \| null` | no | Google Search only: 3-15 Responsive Search Ad headlines (≤30 chars each) |
+| `body.search_keywords` | `Array<Record<string, unknown>> \| null` | no | Google Search only: [{text, match_type: broad\|phrase\|exact, negative: bool}] |
+| `body.selected_channels` | `Record<string, boolean> \| null` | no | Google Video only: placement switches — youtube_in_stream \| youtube_in_feed \| youtube_shorts \| discover \| gmail \| display \| maps (true/false) |
+| `body.special_ad_categories` | `Array<string> \| null` | no | Meta special ad categories: HOUSING \| EMPLOYMENT \| CREDIT \| FINANCIAL_PRODUCTS_SERVICES \| ISSUES_ELECTIONS_POLITICS \| ONLINE_GAMBLING_AND_GAMING \| NONE |
+| `body.spend_cap` | `number \| null` | no | Auto-pause once lifetime SERVED spend reaches this (account currency) > 0 |
+| `body.start_date` | `string (date)` | no |  |
+| `body.video_asset_ids` | `Array<integer> \| null` | no | Google Video only: 1-5 ids of the org's ad_video_assets rows to advertise |
+| `body.video_business_name` | `string \| null` | no | Google Video only: advertiser/brand name shown on the ad (≤25 chars) default `""`, max length 25 |
+| `body.video_cta` | `string \| null` | no | Google Video only: CallToActionType enum value (e.g. LEARN_MORE, SIGN_UP) default `"LEARN_MORE"` |
+| `body.video_descriptions` | `Array<string> \| null` | no | Google Video only: 3-5 descriptions (≤90 chars each) |
+| `body.video_headlines` | `Array<string> \| null` | no | Google Video only: 3-5 headlines (≤40 chars each) |
+| `body.video_long_headlines` | `Array<string> \| null` | no | Google Video only: 3-5 long headlines (≤90 chars each) |
+
+**Returns** `ApiResponse_AdPayload_`: the envelope `{ data: AdPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.adCampaigns.launchAdCampaign({ path: { config_id: 123 }, body: {} });
+```
+
+---
+
+<a id="op-listadcampaigns"></a>
+
+### `g8.api.adCampaigns.listAdCampaigns(input?)`
+
+**List Ad Campaigns**
+
+- HTTP: `GET /api/v1/ad-campaigns`
+- operationId: `list_ad_campaigns_ad_campaigns_get` (also callable as `g8.api.call("list_ad_campaigns_ad_campaigns_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `ads:read`
+
+List the org's paid ad campaigns.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.platform` | `string \| null` | no | Filter by platform: google \| linkedin |
+
+**Returns** `ApiResponse_list_AdCampaignResponse__`: the envelope `{ data: Array<AdCampaignResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AdCampaignResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `integer` | yes |  |
+| `name` | `string` | yes |  |
+| `platform` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `sync_config_id` | `integer` | yes |  |
+| `ad_count` | `integer` | no | Number of live (non-archived) ads in this campaign default `0` |
+| `created_at` | `string \| null` | no |  |
+| `currency` | `string \| null` | no |  |
+| `daily_budget` | `number \| null` | no |  |
+| `end_date` | `string \| null` | no |  |
+| `google_campaign_subtype` | `string \| null` | no |  |
+| `launched_at` | `string \| null` | no |  |
+| `objective` | `string \| null` | no |  |
+| `platform_campaign_id` | `string \| null` | no |  |
+| `start_date` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.adCampaigns.listAdCampaigns();
+```
+
+---
+
+<a id="op-listcampaignads"></a>
+
+### `g8.api.adCampaigns.listCampaignAds(input)`
+
+**List Campaign Ads**
+
+- HTTP: `GET /api/v1/ad-campaigns/{campaign_id}/ads`
+- operationId: `list_campaign_ads_ad_campaigns__campaign_id__ads_get` (also callable as `g8.api.call("list_campaign_ads_ad_campaigns__campaign_id__ads_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `ads:read`
+
+List the ads in a campaign.
+
+Always a collection. A campaign launched before per-ad control existed
+returns its single implicit ad, promoted to a real slot on first read so the
+caller receives a stable id it can act on.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `integer` | yes | Ad campaign ID |
+| `query.include_archived` | `boolean` | no | default `false` |
+
+**Returns** `ApiResponse_AdListResponse_`: the envelope `{ data: AdListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AdListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `ads` | `Array<AdResponse>` | yes |  |
+| `campaign_id` | `integer` | yes |  |
+| `count` | `integer` | yes |  |
+| `platform` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.adCampaigns.listCampaignAds({ path: { campaign_id: 123 } });
+```
+
+---
+
+<a id="op-previewadcampaignedit"></a>
+
+### `g8.api.adCampaigns.previewAdCampaignEdit(input)`
+
+**Preview Ad Campaign Edit**
+
+- HTTP: `POST /api/v1/ad-campaigns/{campaign_id}/edit-preview`
+- operationId: `preview_ad_campaign_edit_ad_campaigns__campaign_id__edit_preview_post` (also callable as `g8.api.call("preview_ad_campaign_edit_ad_campaigns__campaign_id__edit_preview_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `ads:run`
+
+What an edit WOULD change, without applying any of it.
+
+Same body and same response shape as `PUT /ad-campaigns/{campaign_id}`.
+Reads the campaign's live platform state to diff against and changes
+nothing. Run it first: some changes restart the platform's learning phase.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `integer` | yes | The ad campaign's id. |
+| `body` | `UpdateAdCampaignRequest` | yes | Request body; fields below. |
+
+Body fields (`UpdateAdCampaignRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.action` | `string \| null` | no |  |
+| `body.auto_pause_at` | `string (date-time) \| null` | no | Absolute UTC instant to auto-pause at (ISO-8601 with offset) |
+| `body.auto_pause_tz` | `string \| null` | no | max length 64 |
+| `body.campaign_negative_keywords` | `Array<Record<string, unknown>> \| null` | no | Google only: COMPLETE desired campaign-level negative keywords [{text, match_type}] |
+| `body.clear_auto_stop` | `boolean` | no | default `false` |
+| `body.creative_image_url` | `string \| null` | no | max length 500 |
+| `body.creative_image_url_portrait` | `string \| null` | no | max length 500 |
+| `body.creative_image_url_square` | `string \| null` | no | max length 500 |
+| `body.cta` | `string \| null` | no |  |
+| `body.daily_budget` | `number \| null` | no | > 0 |
+| `body.destination_url` | `string \| null` | no | max length 500 |
+| `body.end_date` | `string (date) \| null` | no |  |
+| `body.geo_targets` | `Array<string> \| null` | no | Google only: COMPLETE list of geo target constant ids, e.g. ["2840"] |
+| `body.headline` | `string \| null` | no | max length 255 |
+| `body.keywords` | `Array<Record<string, unknown>> \| null` | no | Google Search only: COMPLETE desired keyword list [{text, match_type, negative, paused, cpc_bid}] |
+| `body.logo_image_url` | `string \| null` | no | max length 500 |
+| `body.name` | `string \| null` | no | max length 255 |
+| `body.primary_text` | `string \| null` | no | max length 1000 |
+| `body.rsa_descriptions` | `Array<string> \| null` | no | Google Search only: COMPLETE list of 2-4 RSA descriptions (<=90 chars each) |
+| `body.rsa_headlines` | `Array<string> \| null` | no | Google Search only: COMPLETE list of 3-15 RSA headlines (<=30 chars each) |
+| `body.selected_channels` | `Record<string, boolean> \| null` | no | Google Video only: COMPLETE placement map (7 DemandGenSelectedChannels keys) |
+| `body.spend_cap` | `number \| null` | no | > 0 |
+| `body.video_asset_ids` | `Array<integer> \| null` | no | Google Video only: COMPLETE list of 1-5 ad_video_assets ids (None = unchanged) |
+| `body.video_business_name` | `string \| null` | no | Google Video only: ≤25 chars max length 25 |
+| `body.video_cta` | `string \| null` | no | Google Video only: CallToActionType value |
+| `body.video_descriptions` | `Array<string> \| null` | no | Google Video only: COMPLETE list, 3-5 × ≤90 |
+| `body.video_headlines` | `Array<string> \| null` | no | Google Video only: COMPLETE list, 3-5 × ≤40 |
+| `body.video_long_headlines` | `Array<string> \| null` | no | Google Video only: COMPLETE list, 3-5 × ≤90 |
+
+**Returns** `ApiResponse_AdPayload_`: the envelope `{ data: AdPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.adCampaigns.previewAdCampaignEdit({ path: { campaign_id: 123 }, body: {} });
+```
+
+---
+
+<a id="op-refreshallcampaignstatuses"></a>
+
+### `g8.api.adCampaigns.refreshAllCampaignStatuses(input?)`
+
+**Refresh All Campaign Statuses**
+
+- HTTP: `POST /api/v1/ad-campaigns/status-refresh`
+- operationId: `refresh_all_campaign_statuses_ad_campaigns_status_refresh_post` (also callable as `g8.api.call("refresh_all_campaign_statuses_ad_campaigns_status_refresh_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `ads:run`
+
+Re-read every refreshable campaign's review state from its platform.
+
+504 if the platforms take too long; the campaigns that did refresh keep
+their new state, so a retry is safe and picks up where it stopped.
+
+**Input**: none.
+
+**Returns** `ApiResponse_AdPayload_`: the envelope `{ data: AdPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.adCampaigns.refreshAllCampaignStatuses();
+```
+
+---
+
+<a id="op-refreshcampaignstatus"></a>
+
+### `g8.api.adCampaigns.refreshCampaignStatus(input)`
+
+**Refresh Campaign Status**
+
+- HTTP: `POST /api/v1/ad-campaigns/{campaign_id}/status-refresh`
+- operationId: `refresh_campaign_status_ad_campaigns__campaign_id__status_refresh_post` (also callable as `g8.api.call("refresh_campaign_status_ad_campaigns__campaign_id__status_refresh_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `ads:run`
+
+Re-read one campaign's review state from its platform.
+
+Policy review is ASYNCHRONOUS: a creative can be auto-rejected minutes
+after the platform accepted the campaign, and graph8's copy still says it
+launched. This promotes the platform's real state - `REJECTED`,
+`NEEDS_REVIEW` - into it. A live platform read; nothing is changed on the
+platform.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `integer` | yes | The ad campaign's id. |
+
+**Returns** `ApiResponse_AdPayload_`: the envelope `{ data: AdPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.adCampaigns.refreshCampaignStatus({ path: { campaign_id: 123 } });
+```
+
+---
+
+<a id="op-retrycampaignlaunch"></a>
+
+### `g8.api.adCampaigns.retryCampaignLaunch(input)`
+
+**Retry Campaign Launch**
+
+- HTTP: `POST /api/v1/ad-campaigns/{campaign_id}/retry`
+- operationId: `retry_campaign_launch_ad_campaigns__campaign_id__retry_post` (also callable as `g8.api.call("retry_campaign_launch_ad_campaigns__campaign_id__retry_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `ads:run`
+
+Re-attempt a launch that failed or stalled.
+
+THIS SPENDS THE CUSTOMER'S ADVERTISING BUDGET when it succeeds - the
+campaign goes live on the platform with the budget it was created with.
+Like the launch, a refusal comes back as a 200 whose body `status` is
+`error` - read it. Check `GET /ad-campaigns/{campaign_id}` first: a
+campaign that is already live does not need this, and retrying one whose
+creative was rejected will fail the same way until the creative changes.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `integer` | yes | The ad campaign's id. |
+
+**Returns** `ApiResponse_AdPayload_`: the envelope `{ data: AdPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.adCampaigns.retryCampaignLaunch({ path: { campaign_id: 123 } });
+```
+
+---
+
+<a id="op-setcampaignadstatus"></a>
+
+### `g8.api.adCampaigns.setCampaignAdStatus(input)`
+
+**Set Campaign Ad Status**
+
+- HTTP: `POST /api/v1/ad-campaigns/{campaign_id}/ads/{ad_id}/status`
+- operationId: `set_campaign_ad_status_ad_campaigns__campaign_id__ads__ad_id__status_post` (also callable as `g8.api.call("set_campaign_ad_status_ad_campaigns__campaign_id__ads__ad_id__status_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `ads:run`
+
+Pause or resume one ad, leaving its siblings and the campaign untouched.
+
+Changes what the campaign's budget is spent on, so this needs ``ads:run``.
+A LinkedIn creative still in policy review cannot be paused; that returns a
+400 with an actionable message rather than a raw platform error.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `integer` | yes | Ad campaign ID |
+| `path.ad_id` | `integer` | yes | graph8 ad ID |
+| `body` | `AdStatusRequest` | yes | Request body; fields below. |
+
+Body fields (`AdStatusRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.status` | `"active" \| "paused"` | yes |  |
+
+**Returns** `ApiResponse_AdResponse_`: the envelope `{ data: AdResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AdResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `campaign_id` | `integer` | yes |  |
+| `slot_index` | `integer` | yes |  |
+| `status` | `string` | yes | draft \| launching \| active \| paused \| archived \| failed |
+| `approval_nuance` | `string \| null` | no |  |
+| `copy_assets` | `Record<string, unknown> \| null` | no | Multi-asset copy, e.g. {rsa_headlines: [...], rsa_descriptions: [...]} |
+| `created_at` | `string \| null` | no |  |
+| `creative_image_url` | `string \| null` | no |  |
+| `creative_image_url_portrait` | `string \| null` | no |  |
+| `creative_image_url_square` | `string \| null` | no |  |
+| `cta` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `destination_url` | `string \| null` | no |  |
+| `error_message` | `string \| null` | no |  |
+| `headline` | `string \| null` | no |  |
+| `id` | `integer \| null` | no | graph8 ad id, stable across creative replacements. Null only for a campaign launched before per-ad control, until its first read. |
+| `launched_at` | `string \| null` | no |  |
+| `logo_image_url` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `platform_ad_id` | `string \| null` | no | Current platform handle. Changes when the creative is replaced. |
+| `policy_topics` | `Array<Record<string, unknown>> \| null` | no |  |
+| `primary_text` | `string \| null` | no |  |
+| `source_ad_creative_id` | `string \| null` | no | The Studio creative this ad was built from, when it came from Studio |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.adCampaigns.setCampaignAdStatus({ path: { campaign_id: 123, ad_id: 123 }, body: { status: "active" } });
+```
+
+---
+
+<a id="op-updateadcampaign"></a>
+
+### `g8.api.adCampaigns.updateAdCampaign(input)`
+
+**Update Ad Campaign**
+
+- HTTP: `PUT /api/v1/ad-campaigns/{campaign_id}`
+- operationId: `update_ad_campaign_ad_campaigns__campaign_id__put` (also callable as `g8.api.call("update_ad_campaign_ad_campaigns__campaign_id__put", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `ads:run`
+
+Edit a LIVE campaign: budget, schedule, creative, keywords, ad copy,
+targeting, pause or resume.
+
+Omitted fields are left alone; an unknown field is a 422 (the app's model
+forbids extras, so a typo cannot silently do nothing). Read
+`GET /ad-campaigns/{campaign_id}/editable` first - the platform refuses
+some changes on some campaign types and states.
+
+A 200 is NOT blanket success: the response `status` is `partial` whenever
+any single change failed, and `changes[]` says which.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `integer` | yes | The ad campaign's id. |
+| `body` | `UpdateAdCampaignRequest` | yes | Request body; fields below. |
+
+Body fields (`UpdateAdCampaignRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.action` | `string \| null` | no |  |
+| `body.auto_pause_at` | `string (date-time) \| null` | no | Absolute UTC instant to auto-pause at (ISO-8601 with offset) |
+| `body.auto_pause_tz` | `string \| null` | no | max length 64 |
+| `body.campaign_negative_keywords` | `Array<Record<string, unknown>> \| null` | no | Google only: COMPLETE desired campaign-level negative keywords [{text, match_type}] |
+| `body.clear_auto_stop` | `boolean` | no | default `false` |
+| `body.creative_image_url` | `string \| null` | no | max length 500 |
+| `body.creative_image_url_portrait` | `string \| null` | no | max length 500 |
+| `body.creative_image_url_square` | `string \| null` | no | max length 500 |
+| `body.cta` | `string \| null` | no |  |
+| `body.daily_budget` | `number \| null` | no | > 0 |
+| `body.destination_url` | `string \| null` | no | max length 500 |
+| `body.end_date` | `string (date) \| null` | no |  |
+| `body.geo_targets` | `Array<string> \| null` | no | Google only: COMPLETE list of geo target constant ids, e.g. ["2840"] |
+| `body.headline` | `string \| null` | no | max length 255 |
+| `body.keywords` | `Array<Record<string, unknown>> \| null` | no | Google Search only: COMPLETE desired keyword list [{text, match_type, negative, paused, cpc_bid}] |
+| `body.logo_image_url` | `string \| null` | no | max length 500 |
+| `body.name` | `string \| null` | no | max length 255 |
+| `body.primary_text` | `string \| null` | no | max length 1000 |
+| `body.rsa_descriptions` | `Array<string> \| null` | no | Google Search only: COMPLETE list of 2-4 RSA descriptions (<=90 chars each) |
+| `body.rsa_headlines` | `Array<string> \| null` | no | Google Search only: COMPLETE list of 3-15 RSA headlines (<=30 chars each) |
+| `body.selected_channels` | `Record<string, boolean> \| null` | no | Google Video only: COMPLETE placement map (7 DemandGenSelectedChannels keys) |
+| `body.spend_cap` | `number \| null` | no | > 0 |
+| `body.video_asset_ids` | `Array<integer> \| null` | no | Google Video only: COMPLETE list of 1-5 ad_video_assets ids (None = unchanged) |
+| `body.video_business_name` | `string \| null` | no | Google Video only: ≤25 chars max length 25 |
+| `body.video_cta` | `string \| null` | no | Google Video only: CallToActionType value |
+| `body.video_descriptions` | `Array<string> \| null` | no | Google Video only: COMPLETE list, 3-5 × ≤90 |
+| `body.video_headlines` | `Array<string> \| null` | no | Google Video only: COMPLETE list, 3-5 × ≤40 |
+| `body.video_long_headlines` | `Array<string> \| null` | no | Google Video only: COMPLETE list, 3-5 × ≤90 |
+
+**Returns** `ApiResponse_AdPayload_`: the envelope `{ data: AdPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.adCampaigns.updateAdCampaign({ path: { campaign_id: 123 }, body: {} });
+```
+
+---
+
+<a id="op-updatecampaignad"></a>
+
+### `g8.api.adCampaigns.updateCampaignAd(input)`
+
+**Update Campaign Ad**
+
+- HTTP: `PATCH /api/v1/ad-campaigns/{campaign_id}/ads/{ad_id}`
+- operationId: `update_campaign_ad_ad_campaigns__campaign_id__ads__ad_id__patch` (also callable as `g8.api.call("update_campaign_ad_ad_campaigns__campaign_id__ads__ad_id__patch", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `ads:run`
+
+Edit one ad's creative.
+
+Check ``replaced_platform_ad`` in the response: on a live campaign most
+creative edits archive the platform ad and create a new one, restarting
+policy review and delivery learning. The graph8 ad id and its measurement
+history survive that.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.campaign_id` | `integer` | yes | Ad campaign ID |
+| `path.ad_id` | `integer` | yes | graph8 ad ID |
+| `body` | `AdUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`AdUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.copy_assets` | `Record<string, unknown> \| null` | no |  |
+| `body.creative_image_url` | `string \| null` | no | max length 500 |
+| `body.creative_image_url_portrait` | `string \| null` | no | max length 500 |
+| `body.creative_image_url_square` | `string \| null` | no | max length 500 |
+| `body.cta` | `string \| null` | no | max length 50 |
+| `body.description` | `string \| null` | no | max length 1000 |
+| `body.destination_url` | `string \| null` | no | max length 500 |
+| `body.headline` | `string \| null` | no | max length 255 |
+| `body.logo_image_url` | `string \| null` | no | max length 500 |
+| `body.name` | `string \| null` | no | max length 255 |
+| `body.primary_text` | `string \| null` | no | max length 1000 |
+| `body.source_ad_creative_id` | `string \| null` | no | max length 64 |
+
+**Returns** `ApiResponse_AdUpdateResponse_`: the envelope `{ data: AdUpdateResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AdUpdateResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `ad` | `AdResponse` | yes |  |
+| `changed` | `Array<string>` | yes |  |
+| `replaced_platform_ad` | `boolean` | yes | True when the platform ad was recreated; review and learning restart |
+| `consequences` | `Array<string>` | no | policy_review \| learning_reset |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.adCampaigns.updateCampaignAd({ path: { campaign_id: 123, ad_id: 123 }, body: {} });
+```
+
+---
+
+<a id="op-uploadadimage"></a>
+
+### `g8.api.adCampaigns.uploadAdImage(input?)`
+
+**Upload Ad Image**
+
+- HTTP: `POST /api/v1/ad-campaigns/images`
+- operationId: `upload_ad_image_ad_campaigns_images_post` (also callable as `g8.api.call("upload_ad_image_ad_campaigns_images_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `ads:run`
+
+Upload an ad creative image and get back the public URL a launch takes.
+
+The app's own checks run unchanged: 10 MB, and the file's MAGIC BYTES decide
+its type rather than its name or declared content type. SVG is refused with
+a 422 - no ad platform accepts it; rasterise first.
+
+**Input**: none.
+
+**Returns** `ApiResponse_AdPayload_`: the envelope `{ data: AdPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.adCampaigns.uploadAdImage();
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-adbatchresultitem"></a>
+
+### `AdBatchResultItem`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `index` | `integer` | yes |  |
+| `status` | `string` | yes |  |
+| `ad` | `AdResponse \| null` | no |  |
+| `error` | `string \| null` | no |  |