late-sdk 0.0.899 → 0.0.901

data/openapi.yaml

@@ -804,6 +804,27 @@ components:
                   effective_account_limit: 2000
                   current_account_count: 2000
   schemas:
+    AdTracking:
+      type: object
+      description: "Meta only. Attaches pixel measurement to the ad regardless of the optimization goal (the \"Website events\" tracking row in Ads Manager). `pixelId` becomes the ad's `tracking_specs` (offsite_conversion + fb_pixel); `urlTags` is stored on the new creative as `url_tags` and retained on the ad for compatibility. Applied on the legacy single-creative shape, every ad of the multi-creative shape, and the attach shape. NOTE: tracking lives on the AD object and is not inherited from the ad set, so pass it on EVERY attach call that should carry the pixel."
+      properties:
+        pixelId: { type: string, description: "Meta Pixel ID to attach for offsite-conversion measurement." }
+        urlTags:
+          type: array
+          description: "Click-URL params stored on the creative as `url_tags` and returned by GET /v1/ads/{adId}/tracking-tags. App-promotion linkUrl stays byte-identical to promotedObject.objectStoreUrl. Meta dynamic macros ({{ad.id}}, {{campaign.id}}, {{placement}}, ...) are sent through unescaped so Meta expands them; every other character is percent-encoded."
+          items:
+            type: object
+            required: [key, value]
+            properties:
+              key: { type: string }
+              value: { type: string }
+    MetaInstagramIdentityRef:
+      type: object
+      required: [igUserId, username]
+      properties:
+        igUserId: { type: string, description: "Instagram identity ID." }
+        username: { type: string, description: "Instagram username; empty when Meta does not expose it." }
+        profilePictureUrl: { type: string, description: "Profile picture URL when available." }
     GoogleBusinessReview:
       type: object
       description: A Google Business Profile review, as returned by every gmb-reviews read endpoint.
@@ -889,6 +910,7 @@ components:
         creativeFeatures:
           $ref: '#/components/schemas/MetaCreativeFeatures'
           description: 'Meta enhancement settings for single or attached ads, and defaults for creatives[]. An item replaces the entire map, including with an empty object.'
+        tracking: { $ref: '#/components/schemas/AdTracking' }
         accountId:
           type: string
           minLength: 1
@@ -8812,6 +8834,114 @@ components:
       properties:
         amount: { type: number }
         type: { type: string, enum: [daily, lifetime] }
+    AdPromotedObject:
+      type: object
+      description: |
+        What the ad optimises against. Behaviour depends on the platform.
+
+        **Meta**: forwarded to the ad set's `promoted_object` (snake-cased).
+        For `goal: app_promotion`, it is also sent on the campaign only when
+        `isSkadnetworkAttribution: true`. Plain Android app installs keep the
+        existing campaign payload, with the promoted object only on the ad set.
+        POST /v1/ads/campaigns forwards this object only for that explicit SKAN flag.
+        Required for goals whose ad-set optimization_goal points at a specific
+        event/page/app (without it Meta rejects the ad-set create with
+        `error_subcode: 1815430` "Please select a promoted object for your ad set"):
+          - `goal: conversions` / `lead_conversion` (OFFSITE_CONVERSIONS): requires `pixelId` + `customEventType`, or `customConversionId` when optimising against a Custom Conversion (the conversion carries its own event definition). For a pixel CUSTOM event (one you named yourself in CAPI/Events Manager), send `customEventType: OTHER` + `customEventStr` with the event name.
+          - `goal: app_promotion` (APP_INSTALLS): requires `applicationId` + `objectStoreUrl`
+          - `goal: lead_generation` (LEAD_GENERATION): `pageId` is auto-filled from the connected Page when omitted
+
+        Other Meta goals (engagement, traffic, awareness, video_views) ignore this field.
+
+        **TikTok**: used by `goal: conversions` and the Smart+ goals (`smartPlus: true`).
+          - `pixelId` maps to the ad group's `pixel_id`. Required: a TikTok website-conversion
+            ad group without a pixel is rejected with `40002: Please select a pixel`.
+          - `customEventType` maps to the ad group's `optimization_event` (the pixel event to
+            optimise for). Optional on the regular conversions flow, required on Smart+.
+            See the `customEventType` field below for the valid TikTok codes.
+          - `applicationId` (Smart+ `goal: app_promotion` only) maps to the ad group's `app_id`:
+            the App ID of an app registered on the TikTok Ads account (Assets → Events →
+            App Events). Install optimization needs the app's MMP tracking configured.
+
+        The remaining `promotedObject.*` fields are Meta-only. Platforms other than
+        Meta and TikTok ignore `promotedObject` entirely.
+      properties:
+        pixelId:
+          type: string
+          description: |
+            Pixel ID. **Meta:** Facebook Pixel ID, required for `goal: conversions`.
+            Requires `customEventType` alongside it; Meta rejects any promoted_object
+            carrying `pixel_id` without `custom_event_type` (error_subcode 1885014),
+            even when `customConversionId` is also present.
+            **TikTok:** TikTok Pixel ID, required for `goal: conversions`.
+            To discover the pixels an ad account can use, call
+            `GET /v1/accounts/{accountId}/tracking-tags?adAccountId=act_...` (each entry
+            carries `kind` and `ownerAdAccountId`), or
+            `GET /v1/accounts/{accountId}/conversion-destinations`. Note this is a
+            different resource from `GET /v1/ads/{adId}/tracking-tags`, which reads an
+            ad's click-URL params (`url_tags`), not pixels.
+        customEventType:
+          type: string
+          description: |
+            The event the campaign/ad group optimises against.
+
+            **Meta:** standard event like `PURCHASE`, `LEAD`, `COMPLETE_REGISTRATION`,
+            `ADD_TO_CART`. Uppercased internally so callers can pass any case. Required
+            for `goal: conversions`.
+
+            **TikTok:** an `optimization_event` code (UPPER_SNAKE, not Meta's vocabulary
+            and not PascalCase), OR the exact event name shown in TikTok Events Manager
+            (auto-resolved to its code). Must be one of the event types your TikTok
+            Pixel tracks; custom events are not optimizable. Current taxonomy:
+            `SHOPPING` (Purchase), `ON_WEB_CART` (Add to Cart), `INITIATE_ORDER`
+            (Initiate Checkout), `FORM` (Lead), `ON_WEB_REGISTER` (Complete
+            Registration), `ON_WEB_DETAIL` (View Content). `ON_WEB_ORDER` is
+            deprecated. On rejection the error lists the event types your pixel
+            actually tracks. Optional for `goal: conversions`.
+        customEventStr:
+          type: string
+          description: |
+            Meta only. Pixel custom-event name to optimise against (Meta's
+            `custom_event_str`), exactly as it appears in Events Manager and in your
+            CAPI payloads (case-sensitive, not uppercased). Requires
+            `customEventType: OTHER`, and `OTHER` requires this field (400 either way).
+            The same as picking a custom event in Ads Manager's conversion-event
+            dropdown. For rule-based Custom Conversions use `customConversionId`
+            instead.
+        pageId:
+          type: string
+          description: |
+            Facebook Page ID. Used by `goal: lead_generation`. Auto-filled from the
+            connected Page when omitted.
+        applicationId:
+          type: string
+          description: "App ID. Required for `goal: app_promotion`."
+        objectStoreUrl:
+          type: string
+          format: uri
+          description: "App Store / Play Store listing URL. Required for `goal: app_promotion`."
+        customConversionId:
+          type: string
+          description: |
+            Custom Conversion ID, when optimising against one instead of a standard
+            event. Accepted alone by this API, without `pixelId` or `customEventType`.
+            If `pixelId` is also sent, `customEventType` is still required on the
+            promoted_object (Meta rejects `pixel_id` without `custom_event_type`,
+            error_subcode 1885014).
+        productCatalogId:
+          type: string
+          description: "Optional catalog ID. If supplied with productSetId, the set must belong to this catalog. A catalog ID cannot replace productSetId."
+        productSetId:
+          type: string
+          description: "Meta product SET ID from GET /v1/ads/catalogs/{catalogId}/product-sets. Zernio checks that the token can read the set and its product_catalog before creation. A catalog ID or inaccessible set returns a precise 400 naming promotedObject.productSetId. A mismatch with productCatalogId names promotedObject.productCatalogId."
+        offlineConversionDataSetId:
+          type: string
+          description: 'Meta only. Offline event set (dataset) to optimise toward. Post-merger these are datasets: the id is the dataset id (for pixel-backed datasets, the pixel id).'
+        whatsappPhoneNumber:
+          type: string
+          description: 'Meta only. WhatsApp number on messaging-destination ad sets.'
+      additionalProperties: false
+
     TargetingSpec:
       type: object
       description: |
@@ -8829,6 +8959,16 @@ components:
         platforms. Fields a platform cannot honour are rejected at create time with
         `INVALID_FIELD_VALUE` naming the offending field (not silently dropped).
       properties:
+        userOs:
+          type: array
+          minItems: 1
+          items: { type: string, minLength: 1 }
+          description: 'Meta only. Operating systems and version ranges, such as iOS_ver_14.0_and_above or Android. Emitted as user_os. May also be supplied inside targeting.'
+        userDevice:
+          type: array
+          minItems: 1
+          items: { type: string, minLength: 1 }
+          description: 'Meta only. Device models such as iPhone. Emitted as user_device. May also be supplied inside targeting.'
         countries: { type: array, items: { type: string }, description: "ISO 3166-1 alpha-2 country codes (e.g. ['US'])." }
         regions:
           type: array
@@ -9035,6 +9175,135 @@ components:
       enum: [applied, not_returned, unavailable]
       description: 'Meta creative readback result. applied means Meta returned promotion metadata; not_returned means the read succeeded without promotion metadata; unavailable means the read failed. Only applied confirms the returned offer. Missing metadata is not proof that Ads Manager displays the requested Promotion.'
       example: not_returned
+    GoogleSitelink:
+      type: object
+      required:
+      - text
+      - linkUrl
+      properties:
+        text:
+          type: string
+          minLength: 1
+          maxLength: 25
+        linkUrl:
+          type: string
+          format: uri
+        description1:
+          type: string
+          minLength: 1
+          maxLength: 35
+        description2:
+          type: string
+          minLength: 1
+          maxLength: 35
+    GoogleStructuredSnippet:
+      type: object
+      required:
+      - header
+      - values
+      properties:
+        header:
+          type: string
+          enum:
+          - Amenities
+          - Brands
+          - Courses
+          - Degree programs
+          - Destinations
+          - Featured hotels
+          - Insurance coverage
+          - Models
+          - Neighborhoods
+          - Service catalog
+          - Shows
+          - Styles
+          - Types
+        values:
+          type: array
+          minItems: 3
+          maxItems: 10
+          items:
+            type: string
+            minLength: 1
+            maxLength: 25
+    GoogleAssetUpdate:
+      type: object
+      required:
+      - assetResourceName
+      properties:
+        assetResourceName:
+          type: string
+          pattern: ^customers/\d+/assets/\d+$
+          description: "Asset resource name returned by a list operation. Must belong to the selected customer."
+        sitelinkAsset:
+          type: object
+          properties:
+            linkText:
+              type: string
+              minLength: 1
+              maxLength: 25
+            description1:
+              type: string
+              maxLength: 35
+            description2:
+              type: string
+              maxLength: 35
+            linkUrl:
+              type: string
+              format: uri
+              description: "Alias for finalUrls with one URL. Do not supply both."
+          minProperties: 1
+        finalUrls:
+          type: array
+          items:
+            type: string
+            format: uri
+          minItems: 1
+        calloutAsset:
+          type: object
+          required:
+          - calloutText
+          properties:
+            calloutText:
+              type: string
+              minLength: 1
+              maxLength: 25
+        structuredSnippetAsset:
+          $ref: '#/components/schemas/GoogleStructuredSnippet'
+      description: "Supply fields for exactly one asset type per update. finalUrls may accompany sitelinkAsset. Shared asset edits affect every attachment using the asset."
+
+    GoogleRsaHeadline:
+      type: object
+      required:
+      - text
+      properties:
+        text:
+          type: string
+          minLength: 1
+          maxLength: 30
+        pinnedField:
+          type: string
+          enum:
+          - HEADLINE_1
+          - HEADLINE_2
+          - HEADLINE_3
+          description: "Optional fixed headline position. Omit to leave the asset unpinned."
+    GoogleRsaDescription:
+      type: object
+      required:
+      - text
+      properties:
+        text:
+          type: string
+          minLength: 1
+          maxLength: 90
+        pinnedField:
+          type: string
+          enum:
+          - DESCRIPTION_1
+          - DESCRIPTION_2
+          description: "Optional fixed description position. Omit to leave the asset unpinned."
+
     Ad:
       type: object
       properties:
@@ -9191,6 +9460,27 @@ components:
           type: [object, "null"]
           description: Platform-specific creative data. Fields vary by platform.
           properties:
+            headlines:
+              type: array
+              minItems: 3
+              maxItems: 15
+              items:
+                $ref: '#/components/schemas/GoogleRsaHeadline'
+              description: "Google RSA only. Replaces the complete headline list. No padding or truncation on update."
+            descriptions:
+              type: array
+              minItems: 2
+              maxItems: 4
+              items:
+                $ref: '#/components/schemas/GoogleRsaDescription'
+              description: "Google RSA only. Replaces the complete description list. No padding or truncation on update."
+            finalUrls:
+              type: array
+              minItems: 1
+              items:
+                type: string
+                format: uri
+              description: "Google RSA only. Replaces final URLs. Omitted lists stay unchanged."
             thumbnailUrl: { type: [string, "null"], description: Primary thumbnail/image URL }
             imageUrl: { type: string, description: Alternative image URL }
             videoId: { type: [string, "null"], description: "Meta video ID for VIDEO-type ads. Null for non-video ads. Callers that need an embeddable MP4 can call GET /{videoId}?fields=source with the page access token." }
@@ -42919,6 +43209,18 @@ paths:
                   type: string
                   enum: [engagement, traffic, awareness, video_views, lead_generation, lead_conversion, job_applicants, conversions, app_promotion, catalog_sales, page_likes]
                   description: Mapped to the ODAX objective (same mapping as POST /v1/ads/create).
+                isSkadnetworkAttribution:
+                  type: boolean
+                  description: 'Meta app promotion only. Immutable campaign flag. Set true for iOS 14+ SKAdNetwork campaigns and supply promotedObject.applicationId plus promotedObject.objectStoreUrl. The campaign receives promotedObject only when this flag is true. Cannot be changed on an existing campaign.'
+                promotedObject:
+                  $ref: '#/components/schemas/AdPromotedObject'
+                buyingType:
+                  type: string
+                  enum: [AUCTION, RESERVED]
+                  description: 'Meta only. SKAdNetwork app promotion requires AUCTION.'
+                validateOnly:
+                  type: boolean
+                  description: 'Meta only. Runs campaign validation without creating or persisting a campaign; Idempotency-Key storage is bypassed. Returns HTTP 200 with validateOnly true and status VALIDATED.'
                 specialAdCategories:
                   type: array
                   items: { type: string, enum: [HOUSING, EMPLOYMENT, CREDIT, ISSUES_ELECTIONS_POLITICS, FINANCIAL_PRODUCTS_SERVICES, ONLINE_GAMBLING_AND_GAMING] }
@@ -42932,7 +43234,30 @@ paths:
                 bidAmount: { type: number, description: "Whole currency units (USD: 5 = $5.00). Required for LOWEST_COST_WITH_BID_CAP and COST_CAP; ignored otherwise. On Meta, validated here but NOT stored: the campaign object has no bid_amount field, only bid_strategy lives on it, and the amount takes effect once an ad set joins this campaign (existingCampaignId on POST /v1/ads/create) and supplies its own bidAmount there. On Google, stored directly on the campaign's bidding strategy." }
                 roasAverageFloor: { type: number, description: "Decimal ROAS multiplier (2.0 = 2.0x). Required for LOWEST_COST_WITH_MIN_ROAS." }
                 portfolioBidStrategyId: { type: string, pattern: '^\d+$', description: "Google only. Attach an existing portfolio bid strategy (numeric id from GET /v1/ads/bid-strategies) to the new campaign instead of a standard one. Exclusive with bidStrategy." }
+            example:
+              accountId: '69fc524892b3d8e85f893e73'
+              adAccountId: 'act_757082720485182'
+              name: 'iOS app campaign'
+              goal: app_promotion
+              isSkadnetworkAttribution: true
+              promotedObject: { applicationId: '123456789', objectStoreUrl: 'https://apps.apple.com/us/app/id123456789' }
+              buyingType: AUCTION
+              status: PAUSED
+              validateOnly: true
       responses:
+        '200':
+          description: 'Campaign validation passed without creating a campaign.'
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  validateOnly: { type: boolean, description: 'Always true.' }
+                  adAccountId: { type: string }
+                  campaignId: { type: string, const: '', description: 'Empty because no campaign was created.' }
+                  objective: { type: string }
+                  status: { type: string, const: VALIDATED }
+              example: { validateOnly: true, adAccountId: 'act_757082720485182', campaignId: '', objective: OUTCOME_APP_PROMOTION, status: VALIDATED }
         '201':
           description: Campaign created
           content:
@@ -44316,6 +44641,11 @@ paths:
       summary: Get ad details
       description: |
         Returns an ad with its creative, targeting, status, and performance metrics.
+        Google Search ads include current creative.headlines, creative.descriptions and creative.finalUrls,
+        preserving pinnedField. Top-level cachedAt and stale report cache freshness. Google mutations invalidate this read.
+        RSA enrichment requires a stored advertisingChannelType of SEARCH. Ads with an unknown or other channel
+        return their stored details without a Google read. If RSA enrichment fails, the stored ad is returned
+        with HTTP 200 and without cache metadata.
 
         The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad:
         - the Zernio internal `_id` (24-char hex)
@@ -44348,10 +44678,26 @@ paths:
           description: Ad details
           content:
             application/json:
+              example:
+                ad:
+                  platform: google
+                  creative:
+                    headlines:
+                    - { text: "Social Media API", pinnedField: HEADLINE_1 }
+                    - { text: "Schedule Your Posts" }
+                    - { text: "Build With Zernio" }
+                    descriptions:
+                    - { text: "Connect social accounts with one API.", pinnedField: DESCRIPTION_1 }
+                    - { text: "Build social publishing into your application." }
+                    finalUrls: ["https://zernio.com"]
+                cachedAt: null
+                stale: false
               schema:
                 type: object
                 properties:
                   ad: { $ref: '#/components/schemas/Ad' }
+                  cachedAt: { type: [string, "null"], format: date-time, description: "Google RSA details cache timestamp." }
+                  stale: { type: boolean, description: "Whether Google RSA details use the last successful cached response." }
         '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
@@ -44374,7 +44720,11 @@ paths:
           Each list you send becomes the FULL new set of its kind (criteria not in the
           list are removed); a kind left out is untouched. Any other `targeting` field
           returns 400: Google cannot mutate broad targeting post-create without recreating
-          the campaign. `creative` returns 501.
+          the campaign. RSA text updates use top-level `headlines`, `descriptions` and `finalUrls`.
+          Each supplied array replaces the full list; omit a field to preserve it. Use 3-15 headlines
+          (1-30 characters) and 2-4 descriptions (1-90 characters). Omit an asset to remove it;
+          omit pinnedField on an included asset to unpin it. Updates do not pad or truncate text.
+          The legacy creative fields remain unsupported for Google.
         - **LinkedIn**: status, budget, targeting (countries or regions, excludedLocations (countries),
           the B2B facets, and audience segments; applied to the LinkedIn Campaign via
           PARTIAL_UPDATE, and REPLACES the campaign's entire targetingCriteria, not a merge),
@@ -44417,9 +44767,51 @@ paths:
         required: true
         content:
           application/json:
+            examples:
+              googleRsa:
+                summary: "Replace and pin Google RSA text."
+                value:
+                  headlines:
+                  - text: Social Media API
+                    pinnedField: HEADLINE_1
+                  - text: Schedule Your Posts
+                  - text: Build With Zernio
+                  descriptions:
+                  - text: Connect social accounts and schedule posts with the Zernio API.
+                    pinnedField: DESCRIPTION_1
+                  - text: Build social publishing into your application.
+                  finalUrls:
+                  - https://zernio.com
+              metaPromotion:
+                summary: "Remove a Meta promotion."
+                value:
+                  creative:
+                    promotion: null
+                    creativeFeatures: { auto_promotion_tag: OPT_OUT }
             schema:
               type: object
               properties:
+                headlines:
+                  type: array
+                  minItems: 3
+                  maxItems: 15
+                  items:
+                    $ref: '#/components/schemas/GoogleRsaHeadline'
+                  description: "Google RSA only. Replaces the complete headline list. No padding or truncation on update."
+                descriptions:
+                  type: array
+                  minItems: 2
+                  maxItems: 4
+                  items:
+                    $ref: '#/components/schemas/GoogleRsaDescription'
+                  description: "Google RSA only. Replaces the complete description list. No padding or truncation on update."
+                finalUrls:
+                  type: array
+                  minItems: 1
+                  items:
+                    type: string
+                    format: uri
+                  description: "Google RSA only. Replaces final URLs. Omitted lists stay unchanged."
                 status: { type: string, enum: [active, paused] }
                 budget:
                   type: object
@@ -44527,10 +44919,6 @@ paths:
                     videoId: { type: string, description: "Meta only. Reuse an already-uploaded ad video (from POST /v1/ads/videos or GET /v1/ads/videos) instead of re-uploading via videoUrl." }
                     existingCreativeId: { type: string, description: "Meta only. Repoint the ad at an existing library creative (from GET /v1/ads/creatives); all other creative fields are ignored." }
                 name: { type: string, maxLength: 255, description: "Rename the ad. Now propagated to Meta (POST /{ad-id}); non-Meta platforms return 501." }
-            example:
-              creative:
-                promotion: null
-                creativeFeatures: { auto_promotion_tag: OPT_OUT }
       responses:
         '200':
           description: Ad updated
@@ -44621,302 +45009,957 @@ paths:
         '404': { description: Ad not found }
 
   /v1/ads/campaigns/{campaignId}/assets:
+    get:
+      operationId: listCampaignAssets
+      summary: List campaign assets
+      x-resource-group: ads
+      tags:
+      - Ad Campaigns
+      x-platforms:
+      - google
+      description: "Lists directly attached Google assets. Fresh reads are cached for 10 minutes; exhausted quota\
+        \ may return the last successful read with stale=true. Inherited assets are not included."
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: campaignId
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: ^\d+$
+        description: "Numeric Google platform id."
+      - name: accountId
+        in: query
+        required: true
+        schema:
+          type: string
+          pattern: ^[a-fA-F0-9]{24}$
+          description: "Zernio Google Ads connection id."
+      - name: customerId
+        in: query
+        schema:
+          type: string
+          pattern: ^\d+$
+          description: "Google customer id without dashes. Required when the connection has multiple customers."
+      responses:
+        '200':
+          description: "Assets returned."
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  campaignId:
+                    type: string
+                  sitelinks:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        assetResourceName:
+                          type: string
+                        campaignAssetResourceName:
+                          type: string
+                        text:
+                          type: string
+                        linkUrl:
+                          type: string
+                          format: uri
+                        description1:
+                          type: string
+                        description2:
+                          type: string
+                  callouts:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        assetResourceName:
+                          type: string
+                        campaignAssetResourceName:
+                          type: string
+                        calloutText:
+                          type: string
+                  structuredSnippets:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        assetResourceName:
+                          type: string
+                        campaignAssetResourceName:
+                          type: string
+                        header:
+                          type: string
+                        values:
+                          type: array
+                          items:
+                            type: string
+                  cachedAt:
+                    type:
+                    - string
+                    - 'null'
+                    format: date-time
+                    description: "Time of the cached Google read. Null when no cache was used."
+                  stale:
+                    type: boolean
+                    description: "True when exhausted quota required returning the last successful read."
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
     post:
-      x-resource-group: "ads"
       operationId: attachCampaignAssets
-      tags: ["Ad Campaigns"]
-      x-platforms: ["google"]
-      summary: Attach extension assets to a Google Search campaign
-      description: |-
-        Attach sitelinks, callouts and/or structured snippets to an already-existing Google
-        Search campaign. These are the same builders POST /v1/ads/create uses, but without rebuilding
-        the hierarchy. At least one of sitelinks, callouts or structuredSnippets is required.
-
-        Google-only. Other platforms have no equivalent extension surface and return 501.
-
-        Approval status is Google-async; poll `asset.policy_summary` after review. Assets
-        stay in the account library even if the campaign is later deleted.
+      summary: Attach campaign assets
+      x-resource-group: ads
+      tags:
+      - Ad Campaigns
+      x-platforms:
+      - google
+      description: "Creates and attaches sitelinks, callouts and structured snippets in one Google mutation."
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - { name: campaignId, in: path, required: true, schema: { type: string }, description: "Numeric Google platform campaign id." }
+      - name: campaignId
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: ^\d+$
+        description: "Numeric Google platform id."
       requestBody:
         required: true
         content:
           application/json:
             schema:
               type: object
-              required: [accountId]
+              required:
+              - accountId
               properties:
-                accountId: { type: string, description: "Zernio Google Ads SocialAccount id. Resolves the customer id + refresh token." }
-                customerId: { type: string, description: "Numeric Google Ads customer id. Required when the connection has multiple Google Ads accounts; optional (and inferred) when it has only one." }
+                accountId:
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
+                customerId:
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
                 sitelinks:
                   type: array
+                  items:
+                    $ref: '#/components/schemas/GoogleSitelink'
                   minItems: 2
                   maxItems: 20
-                  description: "See POST /v1/ads/create sitelinks, same shape."
-                  items:
-                    type: object
-                    required: [text, linkUrl]
-                    properties:
-                      text: { type: string, minLength: 1, maxLength: 25 }
-                      linkUrl: { type: string, format: uri }
-                      description1: { type: string, minLength: 1, maxLength: 35 }
-                      description2: { type: string, minLength: 1, maxLength: 35 }
                 callouts:
                   type: array
+                  items:
+                    type: string
+                    minLength: 1
+                    maxLength: 25
                   minItems: 1
                   maxItems: 20
-                  items: { type: string, minLength: 1, maxLength: 25 }
                 structuredSnippets:
                   type: array
+                  items:
+                    $ref: '#/components/schemas/GoogleStructuredSnippet'
                   minItems: 1
                   maxItems: 20
-                  items:
-                    type: object
-                    required: [header, values]
-                    properties:
-                      header:
-                        type: string
-                        enum: [Amenities, Brands, Courses, Degree programs, Destinations, Featured hotels, Insurance coverage, Models, Neighborhoods, Service catalog, Shows, Styles, Types]
-                      values:
-                        type: array
-                        minItems: 3
-                        maxItems: 10
-                        items: { type: string, minLength: 1, maxLength: 25 }
+              description: "Provide at least one of sitelinks, callouts or structuredSnippets. Sitelink description1\
+                \ and description2 must be supplied together."
+            example:
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              sitelinks:
+              - text: Pricing
+                linkUrl: https://zernio.com/pricing
+              - text: Documentation
+                linkUrl: https://zernio.com/docs
+              callouts:
+              - Fast setup
+              structuredSnippets:
+              - header: Types
+                values:
+                - Scheduling
+                - Analytics
+                - Messaging
       responses:
         '201':
-          description: Assets attached
+          description: "Assets created and attached."
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  campaignId: { type: string }
-                  sitelinkAssetResourceNames: { type: array, items: { type: string } }
-                  calloutAssetResourceNames: { type: array, items: { type: string } }
-                  structuredSnippetAssetResourceNames: { type: array, items: { type: string } }
-        '400': { description: "Invalid input, Google rejected the assets, an unknown customerId (not one of this connection's Google Ads accounts), or a required customerId missing when the connection has multiple Google Ads accounts" }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '403':
-          description: 'Returned with code `ads_allowance_exceeded` when the team has no payment method on file and has reached the 500 free live ads: add a card to resume.'
-        '422': { description: "No Google Ads customer accounts on this connection. Reconnect Google Ads." }
-        '501': { description: Only supported on Google Ads }
-
-  /v1/ads/campaigns/{campaignId}/analytics:
-    get:
-      x-resource-group: "ads"
-      operationId: getCampaignAnalytics
-      tags: ["Ad Insights"]
-      x-platforms: ["meta", "google", "tiktok", "linkedin", "pinterest", "x"]
-      summary: Get campaign analytics
-      description: |
-        Returns performance analytics for a whole campaign in one call: summary metrics, a daily
-        timeline over the requested date range (summed across the campaign's ads), and optional
-        demographic breakdowns. Breakdowns are fetched live from Meta at the campaign level (one call
-        per dimension, no per-ad fan-out), so an agency dashboard gets campaign-level age/gender/etc.
-        without summing thousands of per-ad reads. `campaignId` is the platform campaign id; pass
-        `platform` when a campaign id could be ambiguous across platforms. If no date range is provided,
-        defaults to the last 90 days. Date range is capped at 730 days max.
-        Google adds searchImpressionShare, searchBudgetLostImpressionShare,
-        searchRankLostImpressionShare, searchTopImpressionShare and searchAbsoluteTopImpressionShare
-        under analytics.summary for the requested inclusive range. These ratios are queried
-        together without daily segmentation and cached for 10 minutes. Unavailable values are
-        null. analytics.impressionShareCache reports cachedAt and stale independently of synced metrics.
-      security:
-        - bearerAuth: []
-      parameters:
-        - { name: campaignId, in: path, required: true, schema: { type: string }, description: "Platform campaign id (platformCampaignId)." }
-        - { name: platform, in: query, schema: { type: string }, description: "Disambiguate when the campaign id exists across platforms (e.g. facebook, instagram)." }
-        - { name: fromDate, in: query, schema: { type: string, format: date }, description: "Start of date range (YYYY-MM-DD). Defaults to 90 days ago." }
-        - { name: toDate, in: query, schema: { type: string, format: date }, description: "End of date range (YYYY-MM-DD). Defaults to today. Max 730-day range." }
-        - name: breakdowns
-          in: query
-          schema: { type: string }
-          description: |
-            Comma-separated breakdown dimensions.
-
-            **Meta**: age, gender, country, publisher_platform, device_platform, region,
-            platform_position, impression_device, video_asset, image_asset, body_asset, title_asset.
-
-            **LinkedIn** (firmographics): job_title, job_function, seniority, industry,
-            company, company_size, country, region. Rows carry the raw pivot `value`
-            plus a resolved `name`. LinkedIn serves these aggregated over the whole
-            range, delays the data 12-24h, and omits segments with fewer than 3 events.
-      responses:
-        '200':
-          description: Campaign analytics
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/CampaignAnalyticsResponse' }
-              example:
-                campaign: { id: "123456789", platform: google }
-                analytics:
-                  summary:
-                    searchImpressionShare: 0.42
-                    searchBudgetLostImpressionShare: 0.13
-                    searchRankLostImpressionShare: 0.45
-                    searchTopImpressionShare: 0.31
-                    searchAbsoluteTopImpressionShare: null
-                  impressionShareCache: { cachedAt: "2026-09-09T10:00:00Z", stale: false }
-                  daily: []
-        '202':
-          description: Historical data is incomplete and backfill remains pending.
-          headers:
-            Retry-After:
-              $ref: '#/components/headers/BackfillRetryAfter'
-          content:
-            application/json:
-              schema:
-                allOf:
-                  - { $ref: '#/components/schemas/CampaignAnalyticsResponse' }
-                  - type: object
-                    required: [backfillPending]
-                    properties:
-                      backfillPending: { type: boolean, description: 'Always true on this response. Part of the requested range is still being backfilled; retry until the request returns 200.' }
+                  campaignId:
+                    type: string
+                  sitelinkAssetResourceNames:
+                    type: array
+                    items:
+                      type: string
+                  calloutAssetResourceNames:
+                    type: array
+                    items:
+                      type: string
+                  structuredSnippetAssetResourceNames:
+                    type: array
+                    items:
+                      type: string
         '400':
-          description: "Invalid parameter (e.g. an unknown `breakdowns` dimension). The message lists the offending value(s) and the supported set."
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/ErrorResponse' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
         '403':
-          description: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.
-        '404': { $ref: '#/components/responses/NotFound' }
-        '429': { description: "Google operations budget or quota exhausted without a cached impression-share result." }
-
-  /v1/ads/preview:
-    post:
-      x-resource-group: "ads"
-      operationId: generateAdPreviews
-      tags: ["Ad Creatives"]
-      x-platforms: ["meta"]
-      summary: Render pre-create ad previews
-      description: |
-        Renders how a creative would look per placement BEFORE any ad exists, via Meta's
-        `/generatepreviews`. Provide exactly one creative source: `existingCreativeId` or `creativeSpec`.
-        Each preview is an HTML `<iframe>` snippet embeddable directly. Unknown `formats` values
-        return Meta's 400 verbatim.
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
+    put:
+      operationId: updateCampaignAssets
+      summary: Update campaign assets
+      x-resource-group: ads
+      tags:
+      - Ad Campaigns
+      x-platforms:
+      - google
+      description: "Edits existing Google assets in place. Send updates with assetResourceName and the fields to change.\
+        \ An asset is shared: changes affect every attachment using it. Omitted fields stay unchanged. The operation\
+        \ consumes the Google operations budget and invalidates affected cached lists."
       security:
-        - bearerAuth: []
+      - bearerAuth: []
+      parameters:
+      - name: campaignId
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: ^\d+$
+        description: "Numeric Google platform id."
       requestBody:
         required: true
         content:
           application/json:
             schema:
               type: object
-              required: [accountId, adAccountId]
+              required:
+              - accountId
+              - updates
               properties:
-                accountId: { type: string, description: "Zernio SocialAccount id used to resolve the Meta token." }
-                adAccountId: { type: string, description: "Platform ad account id (Meta act_<n>, Google customer id, LinkedIn account id, ...)." }
-                formats:
+                accountId:
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
+                customerId:
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
+                updates:
                   type: array
+                  items:
+                    $ref: '#/components/schemas/GoogleAssetUpdate'
                   minItems: 1
-                  maxItems: 10
-                  items: { type: string }
-                  description: "Meta ad_format values, one preview per format. Defaults to [DESKTOP_FEED_STANDARD]."
-                existingCreativeId: { type: string, description: "Preview an existing ad-account creative by id. Mutually exclusive with creativeSpec." }
-                creativeSpec:
-                  type: object
-                  additionalProperties: true
-                  description: "Raw Meta creative spec forwarded verbatim to /generatepreviews. Mutually exclusive with existingCreativeId."
+                  maxItems: 20
+            example:
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              updates:
+              - assetResourceName: customers/1234567890/assets/123
+                calloutAsset:
+                  calloutText: Simple integration
       responses:
         '200':
-          description: Rendered previews
+          description: "Assets returned."
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  previews:
-                    type: array
-                    items:
-                      type: object
-                      properties:
-                        format: { type: string }
-                        html: { type: [string, "null"], description: "Meta's <iframe> snippet; null when Meta returned no preview for the format." }
-        '400': { description: "Invalid input, or Meta rejected the creative spec / ad_format; the message carries Meta's error" }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '429': { description: Meta rate limit reached }
-        '501': { description: Only supported on Meta (facebook/instagram) }
-
-  /v1/ads/{adId}/preview:
-    get:
-      x-resource-group: "ads"
-      operationId: getAdPreviews
-      tags: ["Ad Creatives"]
-      x-platforms: ["meta"]
-      summary: Render previews of an existing ad
-      description: |
-        Renders an EXISTING ad per placement via Meta's `/{ad_id}/previews`. Each preview is an HTML
-        `<iframe>` snippet embeddable directly. Unknown `formats` values return Meta's 400 verbatim.
+                  updated:
+                    type: integer
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
+    delete:
+      operationId: removeCampaignAssets
+      summary: Remove campaign assets
+      x-resource-group: ads
+      tags:
+      - Ad Campaigns
+      x-platforms:
+      - google
+      description: "Removes the specified attachments only. Google assets cannot be deleted. Other attachments remain. assetResourceNames is retained for compatibility."
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - { name: adId, in: path, required: true, schema: { type: string }, description: "Zernio ad id (24-char hex)." }
-        - { name: formats, in: query, schema: { type: string }, description: "Comma-separated Meta ad_format values (max 10), one preview per format. Defaults to DESKTOP_FEED_STANDARD." }
+      - name: campaignId
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: ^\d+$
+        description: "Numeric Google platform id."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - accountId
+              - assetResourceNames
+              - campaignAssetResourceNames
+              properties:
+                accountId:
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
+                customerId:
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
+                assetResourceNames:
+                  type: array
+                  items:
+                    type: string
+                  minItems: 1
+                campaignAssetResourceNames:
+                  type: array
+                  items:
+                    type: string
+                  minItems: 1
+            example:
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              assetResourceNames:
+              - customers/1234567890/assets/123
+              campaignAssetResourceNames:
+              - customers/1234567890/campaignAssets/456~123~CALLOUT
       responses:
         '200':
-          description: Rendered previews
+          description: "Assets returned."
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  adId: { type: string }
-                  previews:
-                    type: array
-                    items:
-                      type: object
-                      properties:
-                        format: { type: string }
-                        html: { type: [string, "null"], description: "Meta's <iframe> snippet; null when Meta returned no preview for the format." }
-        '400': { description: "Invalid input, or Meta rejected the ad_format; the message carries Meta's error" }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '404': { description: Ad not found }
-        '429': { description: Meta rate limit reached }
-        '501': { description: Only supported on Meta (facebook/instagram) }
+                  removed:
+                    type: boolean
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
 
-  /v1/ads/{adId}/media:
+  /v1/ads/ad-sets/{adSetId}/assets:
     get:
-      x-resource-group: "ads"
-      operationId: getAdMedia
-      tags: ["Ad Creatives"]
-      x-platforms: ["meta"]
-      summary: Direct video and image URLs for an ad
-      description: |-
-        Returns the direct signed URLs for every video and image asset used by an ad's live
-        creative, normalised across shapes: single image/video, carousel,
-        Reels/Story (`object_story_spec.video_data`) and dynamic
-        creative (`asset_feed_spec`). Video items include Meta's poster thumbnail and the
-        video's Meta id when available.
-
-        Reads Meta live rather than the stored creative blob because Meta's signed fbcdn
-        URLs carry an `oe=<hex>` expiration (image_url ~24 h, video source ~12 d). Treat
-        URLs as short-lived: re-fetch this endpoint before serving or downloading assets
-        instead of caching URLs beyond that window.
+      operationId: listAdGroupAssets
+      summary: List ad-group assets
+      x-resource-group: ads
+      tags:
+      - Ad Campaigns
+      x-platforms:
+      - google
+      description: "Lists directly attached Google assets. Fresh reads are cached for 10 minutes; exhausted quota\
+        \ may return the last successful read with stale=true. Inherited assets are not included."
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - { name: adId, in: path, required: true, schema: { type: string }, description: "Zernio ad id (24-char hex) or platform ad id." }
+      - name: adSetId
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: ^\d+$
+        description: "Numeric Google platform id."
+      - name: accountId
+        in: query
+        required: true
+        schema:
+          type: string
+          pattern: ^[a-fA-F0-9]{24}$
+          description: "Zernio Google Ads connection id."
+      - name: customerId
+        in: query
+        schema:
+          type: string
+          pattern: ^\d+$
+          description: "Google customer id without dashes. Required when the connection has multiple customers."
       responses:
         '200':
-          description: Media assets
+          description: "Assets returned."
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  adId: { type: string }
-                  platform: { type: string, description: "'facebook' or 'instagram'. Only Meta is supported for now." }
-                  media:
+                  adGroupId:
+                    type: string
+                  sitelinks:
                     type: array
                     items:
                       type: object
                       properties:
-                        type: { type: string, enum: [image, video] }
-                        url: { type: string, description: "Direct file URL (signed; short-lived, see description)." }
-                        thumbnailUrl: { type: string, description: "Video poster URL (videos only)." }
+                        assetResourceName:
+                          type: string
+                        adGroupAssetResourceName:
+                          type: string
+                        text:
+                          type: string
+                        linkUrl:
+                          type: string
+                          format: uri
+                        description1:
+                          type: string
+                        description2:
+                          type: string
+                  callouts:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        assetResourceName:
+                          type: string
+                        adGroupAssetResourceName:
+                          type: string
+                        calloutText:
+                          type: string
+                  structuredSnippets:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        assetResourceName:
+                          type: string
+                        adGroupAssetResourceName:
+                          type: string
+                        header:
+                          type: string
+                        values:
+                          type: array
+                          items:
+                            type: string
+                  cachedAt:
+                    type:
+                    - string
+                    - 'null'
+                    format: date-time
+                    description: "Time of the cached Google read. Null when no cache was used."
+                  stale:
+                    type: boolean
+                    description: "True when exhausted quota required returning the last successful read."
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
+    post:
+      operationId: attachAdGroupAssets
+      summary: Attach ad-group assets
+      x-resource-group: ads
+      tags:
+      - Ad Campaigns
+      x-platforms:
+      - google
+      description: "Creates and attaches sitelinks, callouts and structured snippets in one Google mutation."
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: adSetId
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: ^\d+$
+        description: "Numeric Google platform id."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - accountId
+              properties:
+                accountId:
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
+                customerId:
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
+                sitelinks:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/GoogleSitelink'
+                  minItems: 2
+                  maxItems: 20
+                callouts:
+                  type: array
+                  items:
+                    type: string
+                    minLength: 1
+                    maxLength: 25
+                  minItems: 1
+                  maxItems: 20
+                structuredSnippets:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/GoogleStructuredSnippet'
+                  minItems: 1
+                  maxItems: 20
+              description: "Provide at least one of sitelinks, callouts or structuredSnippets. Sitelink description1\
+                \ and description2 must be supplied together."
+            example:
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              sitelinks:
+              - text: Pricing
+                linkUrl: https://zernio.com/pricing
+              - text: Documentation
+                linkUrl: https://zernio.com/docs
+              callouts:
+              - Fast setup
+              structuredSnippets:
+              - header: Types
+                values:
+                - Scheduling
+                - Analytics
+                - Messaging
+      responses:
+        '201':
+          description: "Assets created and attached."
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  adGroupId:
+                    type: string
+                  sitelinkAssetResourceNames:
+                    type: array
+                    items:
+                      type: string
+                  calloutAssetResourceNames:
+                    type: array
+                    items:
+                      type: string
+                  structuredSnippetAssetResourceNames:
+                    type: array
+                    items:
+                      type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
+    put:
+      operationId: updateAdGroupAssets
+      summary: Update ad-group assets
+      x-resource-group: ads
+      tags:
+      - Ad Campaigns
+      x-platforms:
+      - google
+      description: "Edits existing Google assets in place. Send updates with assetResourceName and the fields to change.\
+        \ An asset is shared: changes affect every attachment using it. Omitted fields stay unchanged. The operation\
+        \ consumes the Google operations budget and invalidates affected cached lists."
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: adSetId
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: ^\d+$
+        description: "Numeric Google platform id."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - accountId
+              - updates
+              properties:
+                accountId:
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
+                customerId:
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
+                updates:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/GoogleAssetUpdate'
+                  minItems: 1
+                  maxItems: 20
+            example:
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              updates:
+              - assetResourceName: customers/1234567890/assets/123
+                calloutAsset:
+                  calloutText: Simple integration
+      responses:
+        '200':
+          description: "Assets returned."
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  updated:
+                    type: integer
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
+    delete:
+      operationId: removeAdGroupAssets
+      summary: Remove ad-group assets
+      x-resource-group: ads
+      tags:
+      - Ad Campaigns
+      x-platforms:
+      - google
+      description: "Removes the specified attachments only. Google assets cannot be deleted. Other attachments remain. assetResourceNames is retained for compatibility."
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: adSetId
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: ^\d+$
+        description: "Numeric Google platform id."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - accountId
+              - assetResourceNames
+              - adGroupAssetResourceNames
+              properties:
+                accountId:
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
+                customerId:
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
+                assetResourceNames:
+                  type: array
+                  items:
+                    type: string
+                  minItems: 1
+                adGroupAssetResourceNames:
+                  type: array
+                  items:
+                    type: string
+                  minItems: 1
+            example:
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              assetResourceNames:
+              - customers/1234567890/assets/123
+              adGroupAssetResourceNames:
+              - customers/1234567890/adGroupAssets/456~123~CALLOUT
+      responses:
+        '200':
+          description: "Assets returned."
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  removed:
+                    type: boolean
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
+
+  /v1/ads/campaigns/{campaignId}/analytics:
+    get:
+      x-resource-group: "ads"
+      operationId: getCampaignAnalytics
+      tags: ["Ad Insights"]
+      x-platforms: ["meta", "google", "tiktok", "linkedin", "pinterest", "x"]
+      summary: Get campaign analytics
+      description: |
+        Returns performance analytics for a whole campaign in one call: summary metrics, a daily
+        timeline over the requested date range (summed across the campaign's ads), and optional
+        demographic breakdowns. Breakdowns are fetched live from Meta at the campaign level (one call
+        per dimension, no per-ad fan-out), so an agency dashboard gets campaign-level age/gender/etc.
+        without summing thousands of per-ad reads. `campaignId` is the platform campaign id; pass
+        `platform` when a campaign id could be ambiguous across platforms. If no date range is provided,
+        defaults to the last 90 days. Date range is capped at 730 days max.
+        Google adds searchImpressionShare, searchBudgetLostImpressionShare,
+        searchRankLostImpressionShare, searchTopImpressionShare and searchAbsoluteTopImpressionShare
+        under analytics.summary for the requested inclusive range. These ratios are queried
+        together without daily segmentation and cached for 10 minutes. Unavailable values are
+        null. analytics.impressionShareCache reports cachedAt and stale independently of synced metrics.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: campaignId, in: path, required: true, schema: { type: string }, description: "Platform campaign id (platformCampaignId)." }
+        - { name: platform, in: query, schema: { type: string }, description: "Disambiguate when the campaign id exists across platforms (e.g. facebook, instagram)." }
+        - { name: fromDate, in: query, schema: { type: string, format: date }, description: "Start of date range (YYYY-MM-DD). Defaults to 90 days ago." }
+        - { name: toDate, in: query, schema: { type: string, format: date }, description: "End of date range (YYYY-MM-DD). Defaults to today. Max 730-day range." }
+        - name: breakdowns
+          in: query
+          schema: { type: string }
+          description: |
+            Comma-separated breakdown dimensions.
+
+            **Meta**: age, gender, country, publisher_platform, device_platform, region,
+            platform_position, impression_device, video_asset, image_asset, body_asset, title_asset.
+
+            **LinkedIn** (firmographics): job_title, job_function, seniority, industry,
+            company, company_size, country, region. Rows carry the raw pivot `value`
+            plus a resolved `name`. LinkedIn serves these aggregated over the whole
+            range, delays the data 12-24h, and omits segments with fewer than 3 events.
+      responses:
+        '200':
+          description: Campaign analytics
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/CampaignAnalyticsResponse' }
+              example:
+                campaign: { id: "123456789", platform: google }
+                analytics:
+                  summary:
+                    searchImpressionShare: 0.42
+                    searchBudgetLostImpressionShare: 0.13
+                    searchRankLostImpressionShare: 0.45
+                    searchTopImpressionShare: 0.31
+                    searchAbsoluteTopImpressionShare: null
+                  impressionShareCache: { cachedAt: "2026-09-09T10:00:00Z", stale: false }
+                  daily: []
+        '202':
+          description: Historical data is incomplete and backfill remains pending.
+          headers:
+            Retry-After:
+              $ref: '#/components/headers/BackfillRetryAfter'
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - { $ref: '#/components/schemas/CampaignAnalyticsResponse' }
+                  - type: object
+                    required: [backfillPending]
+                    properties:
+                      backfillPending: { type: boolean, description: 'Always true on this response. Part of the requested range is still being backfilled; retry until the request returns 200.' }
+        '400':
+          description: "Invalid parameter (e.g. an unknown `breakdowns` dimension). The message lists the offending value(s) and the supported set."
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403':
+          description: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.
+        '404': { $ref: '#/components/responses/NotFound' }
+        '429': { description: "Google operations budget or quota exhausted without a cached impression-share result." }
+
+  /v1/ads/preview:
+    post:
+      x-resource-group: "ads"
+      operationId: generateAdPreviews
+      tags: ["Ad Creatives"]
+      x-platforms: ["meta"]
+      summary: Render pre-create ad previews
+      description: |
+        Renders how a creative would look per placement BEFORE any ad exists, via Meta's
+        `/generatepreviews`. Provide exactly one creative source: `existingCreativeId` or `creativeSpec`.
+        Each preview is an HTML `<iframe>` snippet embeddable directly. Unknown `formats` values
+        return Meta's 400 verbatim.
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [accountId, adAccountId]
+              properties:
+                accountId: { type: string, description: "Zernio SocialAccount id used to resolve the Meta token." }
+                adAccountId: { type: string, description: "Platform ad account id (Meta act_<n>, Google customer id, LinkedIn account id, ...)." }
+                formats:
+                  type: array
+                  minItems: 1
+                  maxItems: 10
+                  items: { type: string }
+                  description: "Meta ad_format values, one preview per format. Defaults to [DESKTOP_FEED_STANDARD]."
+                existingCreativeId: { type: string, description: "Preview an existing ad-account creative by id. Mutually exclusive with creativeSpec." }
+                creativeSpec:
+                  type: object
+                  additionalProperties: true
+                  description: "Raw Meta creative spec forwarded verbatim to /generatepreviews. Mutually exclusive with existingCreativeId."
+      responses:
+        '200':
+          description: Rendered previews
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  previews:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        format: { type: string }
+                        html: { type: [string, "null"], description: "Meta's <iframe> snippet; null when Meta returned no preview for the format." }
+        '400': { description: "Invalid input, or Meta rejected the creative spec / ad_format; the message carries Meta's error" }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '429': { description: Meta rate limit reached }
+        '501': { description: Only supported on Meta (facebook/instagram) }
+
+  /v1/ads/{adId}/preview:
+    get:
+      x-resource-group: "ads"
+      operationId: getAdPreviews
+      tags: ["Ad Creatives"]
+      x-platforms: ["meta"]
+      summary: Render previews of an existing ad
+      description: |
+        Renders an EXISTING ad per placement via Meta's `/{ad_id}/previews`. Each preview is an HTML
+        `<iframe>` snippet embeddable directly. Unknown `formats` values return Meta's 400 verbatim.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: adId, in: path, required: true, schema: { type: string }, description: "Zernio ad id (24-char hex)." }
+        - { name: formats, in: query, schema: { type: string }, description: "Comma-separated Meta ad_format values (max 10), one preview per format. Defaults to DESKTOP_FEED_STANDARD." }
+      responses:
+        '200':
+          description: Rendered previews
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  adId: { type: string }
+                  previews:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        format: { type: string }
+                        html: { type: [string, "null"], description: "Meta's <iframe> snippet; null when Meta returned no preview for the format." }
+        '400': { description: "Invalid input, or Meta rejected the ad_format; the message carries Meta's error" }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { description: Ad not found }
+        '429': { description: Meta rate limit reached }
+        '501': { description: Only supported on Meta (facebook/instagram) }
+
+  /v1/ads/{adId}/media:
+    get:
+      x-resource-group: "ads"
+      operationId: getAdMedia
+      tags: ["Ad Creatives"]
+      x-platforms: ["meta"]
+      summary: Direct video and image URLs for an ad
+      description: |-
+        Returns the direct signed URLs for every video and image asset used by an ad's live
+        creative, normalised across shapes: single image/video, carousel,
+        Reels/Story (`object_story_spec.video_data`) and dynamic
+        creative (`asset_feed_spec`). Video items include Meta's poster thumbnail and the
+        video's Meta id when available.
+
+        Reads Meta live rather than the stored creative blob because Meta's signed fbcdn
+        URLs carry an `oe=<hex>` expiration (image_url ~24 h, video source ~12 d). Treat
+        URLs as short-lived: re-fetch this endpoint before serving or downloading assets
+        instead of caching URLs beyond that window.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: adId, in: path, required: true, schema: { type: string }, description: "Zernio ad id (24-char hex) or platform ad id." }
+      responses:
+        '200':
+          description: Media assets
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  adId: { type: string }
+                  platform: { type: string, description: "'facebook' or 'instagram'. Only Meta is supported for now." }
+                  media:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        type: { type: string, enum: [image, video] }
+                        url: { type: string, description: "Direct file URL (signed; short-lived, see description)." }
+                        thumbnailUrl: { type: string, description: "Video poster URL (videos only)." }
                         videoId: { type: string, description: "Meta video id (videos only), reusable as video.id on the create endpoints." }
                         length: { type: number, description: "Video length in seconds (videos only)." }
                         index: { type: integer, description: "0-based position for carousel children or asset_feed_spec entries." }
@@ -45386,7 +46429,7 @@ paths:
       x-resource-group: "engagement"
       operationId: getAdComments
       tags: ["Ad Accounts"]
-      x-platforms: ["meta"]
+      x-platforms: ["meta", "tiktok"]
       summary: List comments on an ad
       description: |
         Returns comments on an ad's underlying creative post. Useful for moderating or analyzing
@@ -45406,26 +46449,39 @@ paths:
         Instagram account on the profile can read the ad's media, the call returns
         ads_connection_required (the Facebook side, if any, is still readable via ?placement=facebook).
 
-        Meta-only for now. Other ad platforms (TikTok, LinkedIn, Pinterest, Google, X)
-        are not wired to this endpoint and return feature_not_available.
+        TikTok uses the connected TikTok Ads advertiser token and supports both paid video
+        ads and Spark Ads. `since` and `until` select a date window of at most 30 days;
+        the default is the last 30 days. TikTok searches by ad group, so Zernio filters
+        each page to this ad. A page can be empty while `pagination.hasMore` is true.
+        Reuse `pagination.cursor` with the same `limit`; the cursor retains the date window.
+        `placement` is Meta-only and returns a 400 for TikTok.
+
+        TikTok returns replies as separate comments with `parentId`; nested reply fetching
+        is not supported. `canReply` requires a first-level comment and an identity with
+        comment-management permission. `canDelete` reflects TikTok's own-comment deletion
+        capability. `canHide` is supported and `canLike` is false. Use the ad comment
+        reply, hide and delete operations below to moderate TikTok comments.
+        Other platforms return feature_not_available.
 
         Requires the Ads add-on. Response shape matches GET /v1/inbox/comments/{postId}.
 
         The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad:
-        Zernio internal `_id` (24-char hex), Meta's numeric `platformAdId` (the value shipped in
+        Zernio internal `_id` (24-char hex), the numeric `platformAdId` (the value shipped in
         `comment.received` webhooks as `comment.ad.id`), or the creative's
         `effective_object_story_id` / `effective_instagram_media_id`. Caller doesn't need a
         translation step.
       security:
         - bearerAuth: []
       parameters:
-        - { name: adId, in: path, required: true, schema: { type: string }, description: "Internal Zernio ad ID (ObjectId)." }
+        - { name: adId, in: path, required: true, schema: { type: string }, description: "Internal Zernio ad ID or indexed platform ad/post ID." }
         - { name: placement, in: query, schema: { type: string, enum: [facebook, instagram] }, description: "Which side of the ad to return comments for. Omit to default to the Instagram side when present, else Facebook. Returns ad_not_commentable if the ad has no such placement." }
         - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 25 } }
+        - { name: since, in: query, schema: { type: string, format: date }, description: "TikTok-only start date. Defaults to 30 days before until. Maximum window is 30 days." }
+        - { name: until, in: query, schema: { type: string, format: date }, description: "TikTok-only end date. Defaults to today in UTC." }
         - { name: cursor, in: query, schema: { type: string }, description: "Pagination cursor from a previous response." }
       responses:
         '200':
-          description: Comments on the ad
+          description: "Comments on the ad."
           content:
             application/json:
               schema:
@@ -45437,7 +46493,7 @@ paths:
                     type: array
                     items:
                       type: object
-                      description: Normalized comment. Same shape as /v1/inbox/comments/{postId} responses.
+                      description: "Normalized comment. Same shape as /v1/inbox/comments/{postId} responses."
                   pagination:
                     type: object
                     properties:
@@ -45445,15 +46501,20 @@ paths:
                       cursor: { type: string }
                   meta:
                     type: object
-                    required: [platform, placement, adId, platformAdId, effectiveStoryId, accountId, lastUpdated]
+                    required: [platform, adId, accountId, lastUpdated]
                     properties:
-                      platform: { type: string, enum: [facebook, instagram], description: "Which side these comments are on (same as `placement`)." }
+                      platform: { type: string, enum: [facebook, instagram, tiktok], description: "Platform of the comments." }
                       placement: { type: string, enum: [facebook, instagram], description: "The placement these comments are for, useful when you didn't pass ?placement= and want to know which one you got." }
                       adId: { type: string, description: "Internal Zernio ad ID." }
-                      platformAdId: { type: string, description: "Meta ad ID." }
+                      platformAdId: { type: string, description: "Platform ad ID." }
                       effectiveStoryId:
                         type: string
                         description: "Underlying post ID the comments belong to. effective_object_story_id for the Facebook side, effective_instagram_media_id for the Instagram side."
+                      tiktokItemId:
+                        type: [string, "null"]
+                        description: "TikTok-only video item ID. Null when the ad and comments do not expose it."
+                      since: { type: string, format: date, description: "TikTok-only resolved start date." }
+                      until: { type: string, format: date, description: "TikTok-only resolved end date." }
                       facebookAccountId:
                         type: [string, "null"]
                         description: "Facebook-only. The connected Facebook Page SocialAccount these comments were read through. Pass it as `accountId` (with `effectiveStoryId` as the postId) to /v1/inbox/comments to reply/hide/delete. Null when no connected Page was used (then moderation isn't possible)."
@@ -45468,19 +46529,215 @@ paths:
                         description: "Instagram-only. The connected Instagram SocialAccount these comments were read through. Pass it as `accountId` (with `effectiveStoryId` as the postId) to /v1/inbox/comments to reply/hide/delete."
                       accountId: { type: string, description: "Account ID (ads SocialAccount)." }
                       lastUpdated: { type: string, format: date-time }
+              example:
+                status: success
+                comments:
+                  - id: "7512345678901234567"
+                    message: "Can you share more details?"
+                    createdTime: "2026-09-08T10:00:00.000Z"
+                    from: { id: "6123456789123456789", name: "reader", username: "reader", picture: "https://example.com/avatar.jpg", isOwner: false }
+                    likeCount: 4
+                    replyCount: 0
+                    platform: tiktok
+                    url: null
+                    replies: []
+                    isHidden: false
+                    canReply: true
+                    canDelete: false
+                    canHide: true
+                    canLike: false
+                    isLiked: false
+                pagination: { hasMore: false }
+                meta:
+                  platform: tiktok
+                  adId: "507f1f77bcf86cd799439011"
+                  platformAdId: "1790166588666881"
+                  accountId: "507f1f77bcf86cd799439012"
+                  tiktokItemId: "7512345678901234500"
+                  since: "2026-08-10"
+                  until: "2026-09-09"
+                  lastUpdated: "2026-09-09T12:00:00.000Z"
         '400':
           description: |
             Invalid ad ID format, or the ad's creative format does not expose a commentable
             underlying post (code ad_not_commentable).
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403':
-          description: Ads access required (legacy plans need the Ads add-on; included by default on usage-based plans), or ad platform is not Meta (code feature_not_available).
+          description: Ads access required (legacy plans need the Ads add-on; included by default on usage-based plans), or ad platform is not Meta or TikTok (code feature_not_available).
         '404': { $ref: '#/components/responses/NotFound' }
         '422':
           description: |
             Ads account token unavailable, or (for Instagram-placed ads) no connected
             Instagram account on the profile can read the ad's media (code ads_connection_required).
 
+  /v1/ads/{adId}/comments/{commentId}/reply:
+    post:
+      operationId: replyToAdComment
+      summary: Reply to an ad comment
+      tags: ["Ad Accounts"]
+      x-resource-group: "engagement"
+      x-platforms: ["tiktok"]
+      description: |
+        Reply to a first-level TikTok ad comment. Requires a TT_USER or CUSTOMIZED_USER identity with comment-management permission. Replies to replies are rejected. The response commentId identifies the new reply. This operation is not idempotent; do not blindly retry an uncertain response.
+
+        Requires Ads access. The ad is resolved within the caller's accessible profiles.
+        Before moderation, Zernio verifies that the comment belongs to this ad using
+        TikTok's ad-group comment listing. The default search window is the last 30 days.
+        Use since/until for older comments, with at most 30 days between the dates.
+        Lookups scan at most 2,000 ad-group comments; narrow the date window if exceeded.
+        Meta returns 501 feature_not_available with guidance to use the existing inbox
+        comment endpoints and the account/post IDs from GET /v1/ads/{adId}/comments.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: adId, in: path, required: true, schema: { type: string }, description: "Internal Zernio ad ID or indexed platform ad ID." }
+        - { name: commentId, in: path, required: true, schema: { type: string, pattern: '^\d+$' }, description: "TikTok comment ID from the ad comment listing." }
+        - { name: since, in: query, schema: { type: string, format: date }, description: "Start date of the comment lookup window. Defaults to 30 days before until." }
+        - { name: until, in: query, schema: { type: string, format: date }, description: "End date of the comment lookup window. Defaults to today in UTC." }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [text]
+              properties:
+                text: { type: string, minLength: 1, description: "Non-empty reply text." }
+            example: { text: "Thanks for your question!" }
+      responses:
+        '200':
+          description: "Comment action completed."
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [status, commentId]
+                properties:
+                  status: { type: string, enum: [success] }
+                  commentId: { type: string, description: "ID of the created reply or moderated comment." }
+              example: { status: success, commentId: "7512345678901234567" }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403':
+          description: "Ads access or the required TikTok comment capability is unavailable."
+        '404':
+          description: "Ad is inaccessible or the comment was not found on this ad in the selected date window."
+        '422':
+          description: "TikTok Ads connection is unavailable."
+        '501':
+          description: "Moderation on this route supports TikTok. Use the inbox comment routes for Meta."
+        '502':
+          description: "TikTok rejected the request or was unavailable. Inspect platformError for its code and message."
+
+  /v1/ads/{adId}/comments/{commentId}/hide:
+    post:
+      operationId: hideAdComment
+      summary: Hide or unhide an ad comment
+      tags: ["Ad Accounts"]
+      x-resource-group: "engagement"
+      x-platforms: ["tiktok"]
+      description: |
+        Hide or restore a TikTok ad comment. Send hidden=true to hide it or hidden=false to make it public again.
+
+        Requires Ads access. The ad is resolved within the caller's accessible profiles.
+        Before moderation, Zernio verifies that the comment belongs to this ad using
+        TikTok's ad-group comment listing. The default search window is the last 30 days.
+        Use since/until for older comments, with at most 30 days between the dates.
+        Lookups scan at most 2,000 ad-group comments; narrow the date window if exceeded.
+        Meta returns 501 feature_not_available with guidance to use the existing inbox
+        comment endpoints and the account/post IDs from GET /v1/ads/{adId}/comments.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: adId, in: path, required: true, schema: { type: string }, description: "Internal Zernio ad ID or indexed platform ad ID." }
+        - { name: commentId, in: path, required: true, schema: { type: string, pattern: '^\d+$' }, description: "TikTok comment ID from the ad comment listing." }
+        - { name: since, in: query, schema: { type: string, format: date }, description: "Start date of the comment lookup window. Defaults to 30 days before until." }
+        - { name: until, in: query, schema: { type: string, format: date }, description: "End date of the comment lookup window. Defaults to today in UTC." }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [hidden]
+              properties:
+                hidden: { type: boolean, description: "True to hide the comment; false to restore it." }
+            example: { hidden: true }
+      responses:
+        '200':
+          description: "Comment action completed."
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [status, commentId]
+                properties:
+                  status: { type: string, enum: [success] }
+                  commentId: { type: string, description: "ID of the created reply or moderated comment." }
+                  hidden: { type: boolean, description: "The requested visibility state." }
+              example: { status: success, commentId: "7512345678901234567", hidden: true }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403':
+          description: "Ads access or the required TikTok comment capability is unavailable."
+        '404':
+          description: "Ad is inaccessible or the comment was not found on this ad in the selected date window."
+        '422':
+          description: "TikTok Ads connection is unavailable."
+        '501':
+          description: "Moderation on this route supports TikTok. Use the inbox comment routes for Meta."
+        '502':
+          description: "TikTok rejected the request or was unavailable. Inspect platformError for its code and message."
+
+  /v1/ads/{adId}/comments/{commentId}:
+    delete:
+      operationId: deleteAdComment
+      summary: Delete an ad comment
+      tags: ["Ad Accounts"]
+      x-resource-group: "engagement"
+      x-platforms: ["tiktok"]
+      description: |
+        Delete your own TikTok ad comment or reply. TikTok must return can_delete=true for the comment. Other users' comments can be hidden instead.
+
+        Requires Ads access. The ad is resolved within the caller's accessible profiles.
+        Before moderation, Zernio verifies that the comment belongs to this ad using
+        TikTok's ad-group comment listing. The default search window is the last 30 days.
+        Use since/until for older comments, with at most 30 days between the dates.
+        Lookups scan at most 2,000 ad-group comments; narrow the date window if exceeded.
+        Meta returns 501 feature_not_available with guidance to use the existing inbox
+        comment endpoints and the account/post IDs from GET /v1/ads/{adId}/comments.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: adId, in: path, required: true, schema: { type: string }, description: "Internal Zernio ad ID or indexed platform ad ID." }
+        - { name: commentId, in: path, required: true, schema: { type: string, pattern: '^\d+$' }, description: "TikTok comment ID from the ad comment listing." }
+        - { name: since, in: query, schema: { type: string, format: date }, description: "Start date of the comment lookup window. Defaults to 30 days before until." }
+        - { name: until, in: query, schema: { type: string, format: date }, description: "End date of the comment lookup window. Defaults to today in UTC." }
+      responses:
+        '200':
+          description: "Comment action completed."
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [status, commentId]
+                properties:
+                  status: { type: string, enum: [success] }
+                  commentId: { type: string, description: "ID of the created reply or moderated comment." }
+              example: { status: success, commentId: "7512345678901234567" }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403':
+          description: "Ads access or the required TikTok comment capability is unavailable."
+        '404':
+          description: "Ad is inaccessible or the comment was not found on this ad in the selected date window."
+        '422':
+          description: "TikTok Ads connection is unavailable."
+        '501':
+          description: "Moderation on this route supports TikTok. Use the inbox comment routes for Meta."
+        '502':
+          description: "TikTok rejected the request or was unavailable. Inspect platformError for its code and message."
+
   /v1/ads/business-centers:
     get:
       x-resource-group: "ads"
@@ -45736,27 +46993,180 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '501': { description: Only supported on Meta (facebook/instagram) }
 
-  /v1/ads/businesses:
+  /v1/ads/instagram-accounts:
     get:
-      x-resource-group: "ads"
-      operationId: listMetaBusinesses
+      operationId: listAdsInstagramAccounts
+      summary: List Instagram ad identities
+      description: "Discovers identities through connected_instagram_accounts, Page linkage and Page-backed identities, with a best-effort business fallback. Business permission errors do not fail discovery. The resolved object uses the same profile-scoped resolver as ad creation; null means no identity was resolved. Format-specific observed-actor fallbacks at creative creation are not predicted."
       tags: ["Ad Accounts"]
+      x-resource-group: "ads"
       x-platforms: ["meta"]
-      summary: Businesses list
-      description: |-
-        Business Manager portfolios the connected Meta user belongs to (Meta's `/me/businesses`),
-        rows returned verbatim (id, name, verification_status, created_time). Token-scoped, so no
-        `adAccountId` is needed. For TikTok Business Centers use
-        `GET /v1/ads/business-centers`.
       security:
         - bearerAuth: []
       parameters:
-        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token." }
-        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 25 }, description: Rows per page }
-        - { name: after, in: query, schema: { type: string }, description: "Cursor from paging.after of the previous page." }
+        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Zernio Meta Ads or Facebook SocialAccount ID." }
+        - { name: adAccountId, in: query, required: true, schema: { type: string, pattern: '^act_[0-9]+$' }, description: "Meta ad account ID including the act_ prefix." }
       responses:
         '200':
-          description: Businesses (raw Meta shape)
+          description: "Instagram identities and Page linkage."
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [accounts, pages, resolved]
+                properties:
+                  accounts:
+                    type: array
+                    items:
+                      allOf:
+                        - $ref: '#/components/schemas/MetaInstagramIdentityRef'
+                        - type: object
+                          required: [isPageBacked, source]
+                          properties:
+                            isPageBacked: { type: boolean, description: "Whether this is a Page-backed Instagram identity." }
+                            source: { type: string, enum: [ad_account, page_backed, business], description: "Discovery source; Page linkage also uses page_backed." }
+                  pages:
+                    type: array
+                    items:
+                      type: object
+                      required: [pageId, name]
+                      properties:
+                        pageId: { type: string, description: "Facebook Page ID." }
+                        name: { type: string, description: "Facebook Page name." }
+                        instagramBusinessAccount: { $ref: '#/components/schemas/MetaInstagramIdentityRef' }
+                        connectedInstagramAccount: { $ref: '#/components/schemas/MetaInstagramIdentityRef' }
+                  resolved:
+                    type: object
+                    required: [pageId, igUserId, source]
+                    properties:
+                      pageId: { type: [string, "null"], description: "Page selected by the shared ad-creation resolver." }
+                      igUserId: { type: [string, "null"], description: "Instagram identity selected by the shared ad-creation resolver." }
+                      source: { type: [string, "null"], enum: [ad_account, page_backed, business, null], description: "Discovery source of the resolved identity; null when absent from discovery." }
+              example:
+                accounts:
+                  - { igUserId: "17841400000000000", username: "example", isPageBacked: false, source: page_backed }
+                pages:
+                  - pageId: "123456789"
+                    name: "Example Page"
+                    instagramBusinessAccount: { igUserId: "17841400000000000", username: "example" }
+                resolved: { pageId: "123456789", igUserId: "17841400000000000", source: page_backed }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { description: "The account or Meta asset is not accessible." }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { description: "Only supported on Meta Ads and Facebook accounts." }
+
+  /v1/ads/advertisable-applications:
+    get:
+      operationId: listAdvertisableApplications
+      summary: List advertisable apps
+      description: "Lists applications available to a Meta ad account, their supported platforms and unmodified object store URLs. A listed app still needs a configured mobile platform and store URL to run install promotion."
+      tags: ["Ad Accounts"]
+      x-resource-group: "ads"
+      x-platforms: ["meta"]
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Zernio Meta Ads or Facebook SocialAccount ID." }
+        - { name: adAccountId, in: query, required: true, schema: { type: string, pattern: '^act_[0-9]+$' }, description: "Meta ad account ID including the act_ prefix." }
+      responses:
+        '200':
+          description: "Applications available for promotion."
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [applications]
+                properties:
+                  applications:
+                    type: array
+                    items:
+                      type: object
+                      required: [id, name, supportedPlatforms, storeUrls]
+                      properties:
+                        id: { type: string, description: "Meta application ID." }
+                        name: { type: string, description: "Application name." }
+                        supportedPlatforms:
+                          type: array
+                          items: { type: string }
+                          description: "Platform identifiers reported by Meta."
+                        storeUrls:
+                          type: object
+                          additionalProperties: { type: string }
+                          description: "Platform-keyed store URLs returned unchanged by Meta."
+              example:
+                applications:
+                  - id: "123456789"
+                    name: "Example App"
+                    supportedPlatforms: [IOS, ANDROID]
+                    storeUrls: { iphone: "https://apps.apple.com/app/id123456789", google_play: "https://play.google.com/store/apps/details?id=com.example.app" }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { description: "The account or Meta asset is not accessible." }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { description: "Only supported on Meta Ads and Facebook accounts." }
+
+  /v1/ads/ios-fourteen-campaign-limits:
+    get:
+      operationId: getIosFourteenCampaignLimits
+      summary: Get iOS 14 campaign limits
+      description: "Reads Meta iOS 14 campaign limits for an application on an ad account. applicationId is sent as Meta app_id. This read does not establish that the application is configured for iOS promotion."
+      tags: ["Ad Accounts"]
+      x-resource-group: "ads"
+      x-platforms: ["meta"]
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Zernio Meta Ads or Facebook SocialAccount ID." }
+        - { name: adAccountId, in: query, required: true, schema: { type: string, pattern: '^act_[0-9]+$' }, description: "Meta ad account ID including the act_ prefix." }
+        - { name: applicationId, in: query, required: true, schema: { type: string, pattern: '^[0-9]+$' }, description: "Meta application ID from advertisable-applications." }
+      responses:
+        '200':
+          description: "Application campaign limits."
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [limits]
+                properties:
+                  limits:
+                    type: [object, "null"]
+                    properties:
+                      campaignGroupLimit: { type: [number, "null"], description: "Campaign group limit reported by Meta." }
+                      campaignLimit: { type: [number, "null"], description: "Campaign limit reported by Meta." }
+                      campaignGroupLimitsDetails:
+                        type: array
+                        items: {}
+                        description: "Campaign group limit details returned by Meta."
+              example:
+                limits: { campaignGroupLimit: 9, campaignLimit: 5, campaignGroupLimitsDetails: [] }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { description: "The account or Meta asset is not accessible." }
+        '404': { $ref: '#/components/responses/NotFound' }
+        '501': { description: "Only supported on Meta Ads and Facebook accounts." }
+
+  /v1/ads/businesses:
+    get:
+      x-resource-group: "ads"
+      operationId: listMetaBusinesses
+      tags: ["Ad Accounts"]
+      x-platforms: ["meta"]
+      summary: Businesses list
+      description: |-
+        Business Manager portfolios the connected Meta user belongs to (Meta's `/me/businesses`),
+        rows returned verbatim (id, name, verification_status, created_time). Token-scoped, so no
+        `adAccountId` is needed. For TikTok Business Centers use
+        `GET /v1/ads/business-centers`.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token." }
+        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 25 }, description: Rows per page }
+        - { name: after, in: query, schema: { type: string }, description: "Cursor from paging.after of the previous page." }
+      responses:
+        '200':
+          description: Businesses (raw Meta shape)
           content:
             application/json:
               schema:
@@ -46817,453 +48227,1255 @@ paths:
               - "openai"
             description: "Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."
       responses:
-        "200":
-          description: "Successful response."
+        "200":
+          description: "Successful response."
+          content:
+            application/json:
+              schema:
+                type: "object"
+                properties:
+                  removed:
+                    type: "boolean"
+                  customerId:
+                    type: "string"
+                    pattern: "^\\d+$"
+                    description: "Resolved Google Ads customer id."
+              example:
+                removed: true
+                customerId: "9122445560"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: "Ads access and permission to the selected account are required."
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: "Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google."
+        "422":
+          description: "Google Ads connection is missing or unavailable."
+        "429":
+          description: "Google Ads operations budget or platform quota exhausted."
+        "501":
+          description: "Available only on Google Ads."
+  /v1/ads/accounts/negative-keyword-lists/{listId}/keywords:
+    put:
+      x-resource-group: "ads"
+      operationId: "replaceAdNegativeKeywordListKeywords"
+      tags:
+        - "Ad Accounts"
+      x-platforms:
+        - "google"
+      summary: "Replace negative list keywords"
+      description: "Replaces the full desired keyword set. Existing keywords are diffed by normalized text and match type; creates and removals are applied atomically in one mutation. Unchanged criteria retain their ids. Send an empty keywords array to clear the list. Changes affect every campaign using this list. Each create or removal consumes one daily operation; the entire batch must fit the remaining quota."
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: "listId"
+          in: "path"
+          required: true
+          schema:
+            type: "string"
+            pattern: "^\\d+$"
+            description: "Google shared set id."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: "object"
+              additionalProperties: false
+              required:
+                - "accountId"
+                - "keywords"
+              properties:
+                accountId:
+                  type: "string"
+                  pattern: "^[a-fA-F0-9]{24}$"
+                  description: "Zernio SocialAccount id."
+                customerId:
+                  type: "string"
+                  pattern: "^\\d+$"
+                  description: "Connected Google Ads customer id, without dashes. Required when the connection has multiple customers."
+                platform:
+                  type: "string"
+                  enum:
+                    - "facebook"
+                    - "instagram"
+                    - "tiktok"
+                    - "linkedin"
+                    - "pinterest"
+                    - "google"
+                    - "twitter"
+                    - "openai"
+                  description: "Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."
+                keywords:
+                  type: "array"
+                  maxItems: 5000
+                  items:
+                    $ref: "#/components/schemas/KeywordEntry"
+                  description: "Full desired keyword set. Bare strings use broad match. Send [] to clear the list."
+            example:
+              accountId: "69ce75d483e990e1c01ccfe4"
+              customerId: "9122445560"
+              keywords:
+                - "free"
+                - text: "jobs"
+                  matchType: "phrase"
+      responses:
+        "200":
+          description: "Successful response."
+          content:
+            application/json:
+              schema:
+                type: "object"
+                properties:
+                  created:
+                    type: "integer"
+                    description: "New criteria or campaign links created."
+                  removed:
+                    type: "integer"
+                    description: "Existing criteria or campaign links removed."
+                  customerId:
+                    type: "string"
+                    pattern: "^\\d+$"
+                    description: "Resolved Google Ads customer id."
+              example:
+                created: 1
+                removed: 1
+                customerId: "9122445560"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: "Ads access and permission to the selected account are required."
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: "Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google."
+        "422":
+          description: "Google Ads connection is missing or unavailable."
+        "429":
+          description: "Google Ads operations budget or platform quota exhausted."
+        "501":
+          description: "Available only on Google Ads."
+  /v1/ads/campaigns/{campaignId}/negative-keyword-lists:
+    get:
+      x-resource-group: "ads"
+      operationId: "listCampaignNegativeKeywordLists"
+      tags:
+        - "Ad Campaigns"
+      x-platforms:
+        - "google"
+      summary: "List campaign negative lists"
+      description: "Returns shared negative keyword lists attached to the campaign, separate from campaign-level negative keywords. Google Ads shared negative keyword lists (shared_set type NEGATIVE_KEYWORDS). Reads are cached for 10 minutes; quota exhaustion may return the last successful result for up to 7 days with stale=true. Customer selection is limited to this connection and its account scope."
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: "campaignId"
+          in: "path"
+          required: true
+          schema:
+            type: "string"
+            pattern: "^\\d+$"
+            description: "Google campaign id."
+        - name: "platform"
+          in: "query"
+          schema:
+            type: "string"
+            enum:
+              - "facebook"
+              - "instagram"
+              - "tiktok"
+              - "linkedin"
+              - "pinterest"
+              - "google"
+              - "twitter"
+              - "openai"
+            description: "Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."
+      responses:
+        "200":
+          description: "Successful response."
+          content:
+            application/json:
+              schema:
+                type: "object"
+                properties:
+                  lists:
+                    type: "array"
+                    items:
+                      $ref: "#/components/schemas/AdNegativeKeywordList"
+                  customerId:
+                    type: "string"
+                    pattern: "^\\d+$"
+                    description: "Resolved Google Ads customer id."
+                  cachedAt:
+                    type:
+                      - "string"
+                      - "null"
+                    format: "date-time"
+                    description: "Last successful fetch time, or null without cache storage."
+                  stale:
+                    type: "boolean"
+                    description: "True when quota exhaustion caused the last successful cached result to be served."
+              example:
+                lists:
+                  - id: "1234567890"
+                    resourceName: "customers/9122445560/sharedSets/1234567890"
+                    name: "Excluded searches"
+                    memberCount: 2
+                    referenceCount: 1
+                customerId: "9122445560"
+                cachedAt: "2026-09-09T10:00:00Z"
+                stale: false
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: "Ads access and permission to the selected account are required."
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: "Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google."
+        "422":
+          description: "Google Ads connection is missing or unavailable."
+        "429":
+          description: "Google Ads operations budget or platform quota exhausted."
+        "501":
+          description: "Available only on Google Ads."
+    put:
+      x-resource-group: "ads"
+      operationId: "replaceCampaignNegativeKeywordLists"
+      tags:
+        - "Ad Campaigns"
+      x-platforms:
+        - "google"
+      summary: "Replace campaign negative lists"
+      description: "Sets the full desired set of shared negative keyword list associations on this campaign. Send listIds=[] to detach all negative keyword lists. Only campaign_shared_set links are changed; the lists and their keywords are preserved. Every list must belong to the campaign customer and have type NEGATIVE_KEYWORDS."
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: "campaignId"
+          in: "path"
+          required: true
+          schema:
+            type: "string"
+            pattern: "^\\d+$"
+            description: "Google campaign id."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: "object"
+              additionalProperties: false
+              required:
+                - "listIds"
+              properties:
+                platform:
+                  type: "string"
+                  enum:
+                    - "facebook"
+                    - "instagram"
+                    - "tiktok"
+                    - "linkedin"
+                    - "pinterest"
+                    - "google"
+                    - "twitter"
+                    - "openai"
+                  description: "Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."
+                listIds:
+                  type: "array"
+                  maxItems: 20
+                  items:
+                    type: "string"
+                    pattern: "^\\d+$"
+                    description: "Shared negative keyword list id."
+            example:
+              platform: "google"
+              listIds:
+                - "1234567890"
+      responses:
+        "200":
+          description: "Successful response."
+          content:
+            application/json:
+              schema:
+                type: "object"
+                properties:
+                  created:
+                    type: "integer"
+                    description: "New criteria or campaign links created."
+                  removed:
+                    type: "integer"
+                    description: "Existing criteria or campaign links removed."
+                  customerId:
+                    type: "string"
+                    pattern: "^\\d+$"
+                    description: "Resolved Google Ads customer id."
+              example:
+                created: 1
+                removed: 0
+                customerId: "9122445560"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: "Ads access and permission to the selected account are required."
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: "Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google."
+        "422":
+          description: "Google Ads connection is missing or unavailable."
+        "429":
+          description: "Google Ads operations budget or platform quota exhausted."
+        "501":
+          description: "Available only on Google Ads."
+
+  /v1/ads/accounts/callouts:
+    get:
+      operationId: listAccountCallouts
+      summary: List account callouts
+      x-resource-group: ads
+      tags:
+      - Ad Accounts
+      x-platforms:
+      - google
+      description: "Lists directly attached Google assets. Fresh reads are cached for 10 minutes; exhausted quota\
+        \ may return the last successful read with stale=true. Inherited assets are not included. Preserves Google\
+        \ RMF C.75 account-level callouts."
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: accountId
+        in: query
+        required: true
+        schema:
+          type: string
+          pattern: ^[a-fA-F0-9]{24}$
+          description: "Zernio Google Ads connection id."
+      - name: customerId
+        in: query
+        schema:
+          type: string
+          pattern: ^\d+$
+          description: "Google customer id without dashes. Required when the connection has multiple customers."
+      responses:
+        '200':
+          description: "Assets returned."
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  customerId:
+                    type: string
+                  callouts:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        assetId:
+                          type: string
+                        status:
+                          type: string
+                        text:
+                          type: string
+                  cachedAt:
+                    type:
+                    - string
+                    - 'null'
+                    format: date-time
+                    description: "Time of the cached Google read. Null when no cache was used."
+                  stale:
+                    type: boolean
+                    description: "True when exhausted quota required returning the last successful read."
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
+    post:
+      operationId: addAccountCallouts
+      summary: Add account callouts
+      x-resource-group: ads
+      tags:
+      - Ad Accounts
+      x-platforms:
+      - google
+      description: "Creates assets and customer_asset links for this Google customer. Links apply at account level."
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - accountId
+              - callouts
+              properties:
+                accountId:
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
+                customerId:
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
+                callouts:
+                  type: array
+                  items:
+                    type: string
+                    minLength: 1
+                    maxLength: 25
+                  minItems: 1
+                  maxItems: 20
+            example:
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              callouts:
+              - Fast setup
+      responses:
+        '201':
+          description: "Assets created and attached."
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  customerId:
+                    type: string
+                  callouts:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        assetId:
+                          type: string
+                        text:
+                          type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
+    put:
+      operationId: updateAccountCallouts
+      summary: Update account callouts
+      x-resource-group: ads
+      tags:
+      - Ad Accounts
+      x-platforms:
+      - google
+      description: "Edits existing Google assets in place. Send updates with assetResourceName and the fields to change.\
+        \ An asset is shared: changes affect every attachment using it. Omitted fields stay unchanged. The operation\
+        \ consumes the Google operations budget and invalidates affected cached lists."
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - accountId
+              - updates
+              properties:
+                accountId:
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
+                customerId:
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
+                updates:
+                  type: array
+                  items:
+                    type: object
+                    required:
+                    - assetResourceName
+                    properties:
+                      assetResourceName:
+                        type: string
+                        pattern: ^customers/\d+/assets/\d+$
+                        description: "Asset resource name returned by a list operation. Must belong to the selected\
+                          \ customer."
+                      calloutAsset:
+                        type: object
+                        required:
+                        - calloutText
+                        properties:
+                          calloutText:
+                            type: string
+                            minLength: 1
+                            maxLength: 25
+                    description: "Provide at least one field belonging to this asset type."
+                  minItems: 1
+                  maxItems: 20
+            example:
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              updates:
+              - assetResourceName: customers/1234567890/assets/123
+                calloutAsset:
+                  calloutText: Simple integration
+      responses:
+        '200':
+          description: "Assets returned."
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  updated:
+                    type: integer
+                  customerId:
+                    type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
+    delete:
+      operationId: removeAccountCallout
+      summary: Remove account callout
+      x-resource-group: ads
+      tags:
+      - Ad Accounts
+      x-platforms:
+      - google
+      description: "Removes the customer_asset attachment only. The underlying shared asset and its campaign or ad-group\
+        \ attachments remain."
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - accountId
+              - assetId
+              properties:
+                accountId:
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
+                customerId:
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
+                assetId:
+                  type: string
+                  pattern: ^\d+$
+            example:
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              assetId: '123'
+      responses:
+        '200':
+          description: "Assets returned."
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  removed:
+                    type: boolean
+                  customerId:
+                    type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
+
+  /v1/ads/accounts/sitelinks:
+    get:
+      operationId: listAccountSitelinks
+      summary: List account sitelinks
+      x-resource-group: ads
+      tags:
+      - Ad Accounts
+      x-platforms:
+      - google
+      description: "Lists directly attached Google assets. Fresh reads are cached for 10 minutes; exhausted quota\
+        \ may return the last successful read with stale=true. Inherited assets are not included."
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: accountId
+        in: query
+        required: true
+        schema:
+          type: string
+          pattern: ^[a-fA-F0-9]{24}$
+          description: "Zernio Google Ads connection id."
+      - name: customerId
+        in: query
+        schema:
+          type: string
+          pattern: ^\d+$
+          description: "Google customer id without dashes. Required when the connection has multiple customers."
+      responses:
+        '200':
+          description: "Assets returned."
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  customerId:
+                    type: string
+                  sitelinks:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        assetId:
+                          type: string
+                        status:
+                          type: string
+                        assetResourceName:
+                          type: string
+                        customerAssetResourceName:
+                          type: string
+                        text:
+                          type: string
+                        linkUrl:
+                          type: string
+                          format: uri
+                        description1:
+                          type: string
+                        description2:
+                          type: string
+                  cachedAt:
+                    type:
+                    - string
+                    - 'null'
+                    format: date-time
+                    description: "Time of the cached Google read. Null when no cache was used."
+                  stale:
+                    type: boolean
+                    description: "True when exhausted quota required returning the last successful read."
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
+    post:
+      operationId: addAccountSitelinks
+      summary: Add account sitelinks
+      x-resource-group: ads
+      tags:
+      - Ad Accounts
+      x-platforms:
+      - google
+      description: "Creates assets and customer_asset links for this Google customer. Links apply at account level."
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - accountId
+              - sitelinks
+              properties:
+                accountId:
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
+                customerId:
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
+                sitelinks:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/GoogleSitelink'
+                  minItems: 1
+                  maxItems: 20
+            example:
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              sitelinks:
+              - text: Pricing
+                linkUrl: https://zernio.com/pricing
+      responses:
+        '201':
+          description: "Assets created and attached."
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  customerId:
+                    type: string
+                  sitelinks:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        assetId:
+                          type: string
+                        text:
+                          type: string
+                          minLength: 1
+                          maxLength: 25
+                        linkUrl:
+                          type: string
+                          format: uri
+                        description1:
+                          type: string
+                          minLength: 1
+                          maxLength: 35
+                        description2:
+                          type: string
+                          minLength: 1
+                          maxLength: 35
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
+    put:
+      operationId: updateAccountSitelinks
+      summary: Update account sitelinks
+      x-resource-group: ads
+      tags:
+      - Ad Accounts
+      x-platforms:
+      - google
+      description: "Edits existing Google assets in place. Send updates with assetResourceName and the fields to change.\
+        \ An asset is shared: changes affect every attachment using it. Omitted fields stay unchanged. The operation\
+        \ consumes the Google operations budget and invalidates affected cached lists."
+      security:
+      - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+              - accountId
+              - updates
+              properties:
+                accountId:
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
+                customerId:
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
+                updates:
+                  type: array
+                  items:
+                    type: object
+                    required:
+                    - assetResourceName
+                    properties:
+                      assetResourceName:
+                        type: string
+                        pattern: ^customers/\d+/assets/\d+$
+                        description: "Asset resource name returned by a list operation. Must belong to the selected\
+                          \ customer."
+                      sitelinkAsset:
+                        type: object
+                        properties:
+                          linkText:
+                            type: string
+                            minLength: 1
+                            maxLength: 25
+                          description1:
+                            type: string
+                            maxLength: 35
+                          description2:
+                            type: string
+                            maxLength: 35
+                          linkUrl:
+                            type: string
+                            format: uri
+                            description: "Alias for finalUrls with one URL. Do not supply both."
+                        minProperties: 1
+                      finalUrls:
+                        type: array
+                        items:
+                          type: string
+                          format: uri
+                        minItems: 1
+                    description: "Provide at least one field belonging to this asset type."
+                  minItems: 1
+                  maxItems: 20
+            example:
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              updates:
+              - assetResourceName: customers/1234567890/assets/123
+                sitelinkAsset:
+                  linkText: Explore pricing
+                finalUrls:
+                - https://zernio.com/pricing
+      responses:
+        '200':
+          description: "Assets returned."
           content:
             application/json:
               schema:
-                type: "object"
+                type: object
                 properties:
-                  removed:
-                    type: "boolean"
+                  updated:
+                    type: integer
                   customerId:
-                    type: "string"
-                    pattern: "^\\d+$"
-                    description: "Resolved Google Ads customer id."
-              example:
-                removed: true
-                customerId: "9122445560"
-        "400":
-          $ref: "#/components/responses/BadRequest"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "403":
-          description: "Ads access and permission to the selected account are required."
-        "404":
-          $ref: "#/components/responses/NotFound"
-        "409":
-          description: "Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google."
-        "422":
-          description: "Google Ads connection is missing or unavailable."
-        "429":
+                    type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
           description: "Google Ads operations budget or platform quota exhausted."
-        "501":
-          description: "Available only on Google Ads."
-  /v1/ads/accounts/negative-keyword-lists/{listId}/keywords:
-    put:
-      x-resource-group: "ads"
-      operationId: "replaceAdNegativeKeywordListKeywords"
+        '501':
+          description: "Only supported on Google Ads."
+    delete:
+      operationId: removeAccountSitelink
+      summary: Remove account sitelink
+      x-resource-group: ads
       tags:
-        - "Ad Accounts"
+      - Ad Accounts
       x-platforms:
-        - "google"
-      summary: "Replace negative list keywords"
-      description: "Replaces the full desired keyword set. Existing keywords are diffed by normalized text and match type; creates and removals are applied atomically in one mutation. Unchanged criteria retain their ids. Send an empty keywords array to clear the list. Changes affect every campaign using this list. Each create or removal consumes one daily operation; the entire batch must fit the remaining quota."
+      - google
+      description: "Removes the customer_asset attachment only. The underlying shared asset and its campaign or ad-group\
+        \ attachments remain."
       security:
-        - bearerAuth: []
-      parameters:
-        - name: "listId"
-          in: "path"
-          required: true
-          schema:
-            type: "string"
-            pattern: "^\\d+$"
-            description: "Google shared set id."
+      - bearerAuth: []
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              type: "object"
-              additionalProperties: false
+              type: object
               required:
-                - "accountId"
-                - "keywords"
+              - accountId
+              - assetId
               properties:
                 accountId:
-                  type: "string"
-                  pattern: "^[a-fA-F0-9]{24}$"
-                  description: "Zernio SocialAccount id."
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
                 customerId:
-                  type: "string"
-                  pattern: "^\\d+$"
-                  description: "Connected Google Ads customer id, without dashes. Required when the connection has multiple customers."
-                platform:
-                  type: "string"
-                  enum:
-                    - "facebook"
-                    - "instagram"
-                    - "tiktok"
-                    - "linkedin"
-                    - "pinterest"
-                    - "google"
-                    - "twitter"
-                    - "openai"
-                  description: "Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."
-                keywords:
-                  type: "array"
-                  maxItems: 5000
-                  items:
-                    $ref: "#/components/schemas/KeywordEntry"
-                  description: "Full desired keyword set. Bare strings use broad match. Send [] to clear the list."
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
+                assetId:
+                  type: string
+                  pattern: ^\d+$
             example:
-              accountId: "69ce75d483e990e1c01ccfe4"
-              customerId: "9122445560"
-              keywords:
-                - "free"
-                - text: "jobs"
-                  matchType: "phrase"
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              assetId: '123'
       responses:
-        "200":
-          description: "Successful response."
+        '200':
+          description: "Assets returned."
           content:
             application/json:
               schema:
-                type: "object"
+                type: object
                 properties:
-                  created:
-                    type: "integer"
-                    description: "New criteria or campaign links created."
                   removed:
-                    type: "integer"
-                    description: "Existing criteria or campaign links removed."
+                    type: boolean
                   customerId:
-                    type: "string"
-                    pattern: "^\\d+$"
-                    description: "Resolved Google Ads customer id."
-              example:
-                created: 1
-                removed: 1
-                customerId: "9122445560"
-        "400":
-          $ref: "#/components/responses/BadRequest"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "403":
-          description: "Ads access and permission to the selected account are required."
-        "404":
-          $ref: "#/components/responses/NotFound"
-        "409":
-          description: "Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google."
-        "422":
-          description: "Google Ads connection is missing or unavailable."
-        "429":
+                    type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
           description: "Google Ads operations budget or platform quota exhausted."
-        "501":
-          description: "Available only on Google Ads."
-  /v1/ads/campaigns/{campaignId}/negative-keyword-lists:
+        '501':
+          description: "Only supported on Google Ads."
+
+  /v1/ads/accounts/structured-snippets:
     get:
-      x-resource-group: "ads"
-      operationId: "listCampaignNegativeKeywordLists"
+      operationId: listAccountStructuredSnippets
+      summary: List account snippets
+      x-resource-group: ads
       tags:
-        - "Ad Campaigns"
+      - Ad Accounts
       x-platforms:
-        - "google"
-      summary: "List campaign negative lists"
-      description: "Returns shared negative keyword lists attached to the campaign, separate from campaign-level negative keywords. Google Ads shared negative keyword lists (shared_set type NEGATIVE_KEYWORDS). Reads are cached for 10 minutes; quota exhaustion may return the last successful result for up to 7 days with stale=true. Customer selection is limited to this connection and its account scope."
+      - google
+      description: "Lists directly attached Google assets. Fresh reads are cached for 10 minutes; exhausted quota\
+        \ may return the last successful read with stale=true. Inherited assets are not included."
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       parameters:
-        - name: "campaignId"
-          in: "path"
-          required: true
-          schema:
-            type: "string"
-            pattern: "^\\d+$"
-            description: "Google campaign id."
-        - name: "platform"
-          in: "query"
-          schema:
-            type: "string"
-            enum:
-              - "facebook"
-              - "instagram"
-              - "tiktok"
-              - "linkedin"
-              - "pinterest"
-              - "google"
-              - "twitter"
-              - "openai"
-            description: "Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."
+      - name: accountId
+        in: query
+        required: true
+        schema:
+          type: string
+          pattern: ^[a-fA-F0-9]{24}$
+          description: "Zernio Google Ads connection id."
+      - name: customerId
+        in: query
+        schema:
+          type: string
+          pattern: ^\d+$
+          description: "Google customer id without dashes. Required when the connection has multiple customers."
       responses:
-        "200":
-          description: "Successful response."
+        '200':
+          description: "Assets returned."
           content:
             application/json:
               schema:
-                type: "object"
+                type: object
                 properties:
-                  lists:
-                    type: "array"
-                    items:
-                      $ref: "#/components/schemas/AdNegativeKeywordList"
                   customerId:
-                    type: "string"
-                    pattern: "^\\d+$"
-                    description: "Resolved Google Ads customer id."
+                    type: string
+                  structuredSnippets:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        assetId:
+                          type: string
+                        status:
+                          type: string
+                        assetResourceName:
+                          type: string
+                        customerAssetResourceName:
+                          type: string
+                        header:
+                          type: string
+                        values:
+                          type: array
+                          items:
+                            type: string
                   cachedAt:
                     type:
-                      - "string"
-                      - "null"
-                    format: "date-time"
-                    description: "Last successful fetch time, or null without cache storage."
+                    - string
+                    - 'null'
+                    format: date-time
+                    description: "Time of the cached Google read. Null when no cache was used."
                   stale:
-                    type: "boolean"
-                    description: "True when quota exhaustion caused the last successful cached result to be served."
-              example:
-                lists:
-                  - id: "1234567890"
-                    resourceName: "customers/9122445560/sharedSets/1234567890"
-                    name: "Excluded searches"
-                    memberCount: 2
-                    referenceCount: 1
-                customerId: "9122445560"
-                cachedAt: "2026-09-09T10:00:00Z"
-                stale: false
-        "400":
-          $ref: "#/components/responses/BadRequest"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "403":
-          description: "Ads access and permission to the selected account are required."
-        "404":
-          $ref: "#/components/responses/NotFound"
-        "409":
-          description: "Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google."
-        "422":
-          description: "Google Ads connection is missing or unavailable."
-        "429":
+                    type: boolean
+                    description: "True when exhausted quota required returning the last successful read."
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
           description: "Google Ads operations budget or platform quota exhausted."
-        "501":
-          description: "Available only on Google Ads."
-    put:
-      x-resource-group: "ads"
-      operationId: "replaceCampaignNegativeKeywordLists"
+        '501':
+          description: "Only supported on Google Ads."
+    post:
+      operationId: addAccountStructuredSnippets
+      summary: Add account snippets
+      x-resource-group: ads
       tags:
-        - "Ad Campaigns"
+      - Ad Accounts
       x-platforms:
-        - "google"
-      summary: "Replace campaign negative lists"
-      description: "Sets the full desired set of shared negative keyword list associations on this campaign. Send listIds=[] to detach all negative keyword lists. Only campaign_shared_set links are changed; the lists and their keywords are preserved. Every list must belong to the campaign customer and have type NEGATIVE_KEYWORDS."
+      - google
+      description: "Creates assets and customer_asset links for this Google customer. Links apply at account level."
       security:
-        - bearerAuth: []
-      parameters:
-        - name: "campaignId"
-          in: "path"
-          required: true
-          schema:
-            type: "string"
-            pattern: "^\\d+$"
-            description: "Google campaign id."
+      - bearerAuth: []
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              type: "object"
-              additionalProperties: false
+              type: object
               required:
-                - "listIds"
+              - accountId
+              - structuredSnippets
               properties:
-                platform:
-                  type: "string"
-                  enum:
-                    - "facebook"
-                    - "instagram"
-                    - "tiktok"
-                    - "linkedin"
-                    - "pinterest"
-                    - "google"
-                    - "twitter"
-                    - "openai"
-                  description: "Optional courtesy field. The resolved account or campaign determines support; other platforms return 501."
-                listIds:
-                  type: "array"
-                  maxItems: 20
+                accountId:
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
+                customerId:
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
+                structuredSnippets:
+                  type: array
                   items:
-                    type: "string"
-                    pattern: "^\\d+$"
-                    description: "Shared negative keyword list id."
+                    $ref: '#/components/schemas/GoogleStructuredSnippet'
+                  minItems: 1
+                  maxItems: 20
             example:
-              platform: "google"
-              listIds:
-                - "1234567890"
-      responses:
-        "200":
-          description: "Successful response."
-          content:
-            application/json:
-              schema:
-                type: "object"
-                properties:
-                  created:
-                    type: "integer"
-                    description: "New criteria or campaign links created."
-                  removed:
-                    type: "integer"
-                    description: "Existing criteria or campaign links removed."
-                  customerId:
-                    type: "string"
-                    pattern: "^\\d+$"
-                    description: "Resolved Google Ads customer id."
-              example:
-                created: 1
-                removed: 0
-                customerId: "9122445560"
-        "400":
-          $ref: "#/components/responses/BadRequest"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "403":
-          description: "Ads access and permission to the selected account are required."
-        "404":
-          $ref: "#/components/responses/NotFound"
-        "409":
-          description: "Ambiguous campaign or account selection. Use a profile-scoped key. A list still attached to a campaign may also be rejected by Google."
-        "422":
-          description: "Google Ads connection is missing or unavailable."
-        "429":
-          description: "Google Ads operations budget or platform quota exhausted."
-        "501":
-          description: "Available only on Google Ads."
-
-  /v1/ads/accounts/callouts:
-    get:
-      x-resource-group: "ads"
-      operationId: listAccountCallouts
-      tags: ["Ad Accounts"]
-      x-platforms: ["google"]
-      summary: List account-level callout extensions
-      description: |-
-        Google Ads compliance row C.75: callout assets linked at the CUSTOMER
-        level via `customer_asset` (not a campaign or ad group), so they serve
-        fleet-wide across the account. Google only; every other platform
-        returns 501. Cached for the quota window (10 minutes fresh, up to 7
-        days last-good), and gated by the shared Google Ads operations budget
-        on a cache miss. The response carries `cachedAt` and `stale`, set when
-        a quota-exhausted call falls back to the last-good copy instead of a
-        live read.
-      security:
-        - bearerAuth: []
-      parameters:
-        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Google ads SocialAccount id." }
-        - { name: customerId, in: query, schema: { type: string }, description: "Numeric Google Ads customer id (no dashes). Defaults to the account's connected customer." }
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              structuredSnippets:
+              - header: Types
+                values:
+                - Scheduling
+                - Analytics
+                - Messaging
       responses:
-        '200':
-          description: Account-level callouts
+        '201':
+          description: "Assets created and attached."
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  customerId: { type: string }
-                  callouts:
+                  customerId:
+                    type: string
+                  structuredSnippets:
                     type: array
                     items:
                       type: object
                       properties:
-                        assetId: { type: string }
-                        text: { type: string }
-                        status: { type: string, description: "customer_asset.status, e.g. ENABLED, REMOVED, PAUSED." }
-                  cachedAt: { type: [string, "null"], format: date-time, description: "When this list was fetched from Google. Null when it was never served from cache." }
-                  stale: { type: boolean, description: "True when Google's daily API quota was exhausted and this is the last successful fetch, not a live read." }
-        '400': { $ref: '#/components/responses/BadRequest' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
+                        assetId:
+                          type: string
+                        header:
+                          type: string
+                          enum:
+                          - Amenities
+                          - Brands
+                          - Courses
+                          - Degree programs
+                          - Destinations
+                          - Featured hotels
+                          - Insurance coverage
+                          - Models
+                          - Neighborhoods
+                          - Service catalog
+                          - Shows
+                          - Styles
+                          - Types
+                        values:
+                          type: array
+                          minItems: 3
+                          maxItems: 10
+                          items:
+                            type: string
+                            minLength: 1
+                            maxLength: 25
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
         '403':
-          description: Ads access required (Ads add-on on legacy plans, included on usage-based plans).
-        '404': { $ref: '#/components/responses/NotFound' }
-        '429': { description: Google Ads operations budget exhausted; retry later }
-        '501': { description: Only available on Google Ads accounts }
-
-    post:
-      x-resource-group: "ads"
-      operationId: addAccountCallouts
-      tags: ["Ad Accounts"]
-      x-platforms: ["google"]
-      summary: Add account-level callout extensions
-      description: |-
-        Creates one asset plus one `customerAsset` link (field type CALLOUT)
-        per callout text, in a single mutate. Google only; every other
-        platform returns 501.
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
+    put:
+      operationId: updateAccountStructuredSnippets
+      summary: Update account snippets
+      x-resource-group: ads
+      tags:
+      - Ad Accounts
+      x-platforms:
+      - google
+      description: "Edits existing Google assets in place. Send updates with assetResourceName and the fields to change.\
+        \ An asset is shared: changes affect every attachment using it. Omitted fields stay unchanged. The operation\
+        \ consumes the Google operations budget and invalidates affected cached lists."
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       requestBody:
         required: true
         content:
           application/json:
             schema:
               type: object
-              required: [accountId, callouts]
+              required:
+              - accountId
+              - updates
               properties:
-                accountId: { type: string, description: "Zernio SocialAccount id owning the Google Ads connection." }
-                customerId: { type: string, description: "Numeric Google Ads customer id. Only required when the connection has more than one." }
-                callouts:
+                accountId:
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
+                customerId:
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
+                updates:
                   type: array
+                  items:
+                    type: object
+                    required:
+                    - assetResourceName
+                    properties:
+                      assetResourceName:
+                        type: string
+                        pattern: ^customers/\d+/assets/\d+$
+                        description: "Asset resource name returned by a list operation. Must belong to the selected\
+                          \ customer."
+                      structuredSnippetAsset:
+                        $ref: '#/components/schemas/GoogleStructuredSnippet'
+                    description: "Provide at least one field belonging to this asset type."
                   minItems: 1
                   maxItems: 20
-                  items: { type: string, minLength: 1, maxLength: 25 }
-                  description: 'Callout text, 1-25 characters each; up to 20 per request (Google''s CalloutAsset limits).'
+            example:
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              updates:
+              - assetResourceName: customers/1234567890/assets/123
+                structuredSnippetAsset:
+                  header: Types
+                  values:
+                  - Scheduling
+                  - Reporting
+                  - Messaging
       responses:
-        '201':
-          description: Callouts created
+        '200':
+          description: "Assets returned."
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  customerId: { type: string }
-                  callouts:
-                    type: array
-                    items:
-                      type: object
-                      properties:
-                        assetId: { type: string }
-                        text: { type: string }
-        '400': { $ref: '#/components/responses/BadRequest' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
+                  updated:
+                    type: integer
+                  customerId:
+                    type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
         '403':
-          description: Ads access required (Ads add-on on legacy plans, included on usage-based plans).
-        '404': { $ref: '#/components/responses/NotFound' }
-        '501': { description: Only supported on Google Ads }
-
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
     delete:
-      x-resource-group: "ads"
-      operationId: removeAccountCallout
-      tags: ["Ad Accounts"]
-      x-platforms: ["google"]
-      summary: Remove an account-level callout extension
-      description: |-
-        Removes the `customerAsset` link (`customers/{cid}/customerAssets/{assetId}~CALLOUT`).
-        Google only; every other platform returns 501.
+      operationId: removeAccountStructuredSnippet
+      summary: Remove account snippet
+      x-resource-group: ads
+      tags:
+      - Ad Accounts
+      x-platforms:
+      - google
+      description: "Removes the customer_asset attachment only. The underlying shared asset and its campaign or ad-group\
+        \ attachments remain."
       security:
-        - bearerAuth: []
+      - bearerAuth: []
       requestBody:
         required: true
         content:
           application/json:
             schema:
               type: object
-              required: [accountId, assetId]
+              required:
+              - accountId
+              - assetId
               properties:
-                accountId: { type: string, description: "Zernio SocialAccount id owning the Google Ads connection." }
-                customerId: { type: string, description: "Numeric Google Ads customer id. Only required when the connection has more than one." }
-                assetId: { type: string, description: "Numeric asset id from GET /v1/ads/accounts/callouts." }
+                accountId:
+                  type: string
+                  pattern: ^[a-fA-F0-9]{24}$
+                  description: "Zernio Google Ads connection id."
+                customerId:
+                  type: string
+                  pattern: ^\d+$
+                  description: "Google customer id without dashes. Required when the connection has multiple customers."
+                assetId:
+                  type: string
+                  pattern: ^\d+$
+            example:
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              assetId: '123'
       responses:
         '200':
-          description: Callout removed
+          description: "Assets returned."
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  removed: { type: boolean }
-                  customerId: { type: string }
-        '400': { $ref: '#/components/responses/BadRequest' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
+                  removed:
+                    type: boolean
+                  customerId:
+                    type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
         '403':
-          description: Ads access required (Ads add-on on legacy plans, included on usage-based plans).
-        '404': { $ref: '#/components/responses/NotFound' }
-        '501': { description: Only supported on Google Ads }
+          description: "Ads access is required."
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          description: "Google Ads operations budget or platform quota exhausted."
+        '501':
+          description: "Only supported on Google Ads."
 
   /v1/ads/accounts/finance:
     get:
@@ -47922,20 +50134,7 @@ paths:
                 campaignName: { type: string, maxLength: 255, description: "Meta only. Exact campaign name. Overrides the default `<name> - Campaign`." }
                 adSetName: { type: string, maxLength: 255, description: "Meta only. Exact ad set name. Overrides the default `<name> - Ad Set`. (For per-ad names on the multi-creative shape, set `name` on each `creatives[]` entry.)" }
                 adName: { type: string, maxLength: 255, description: "Meta only. Exact ad name (the single-creative ad object's name). Overrides the default, which is `name`. (For per-ad names on the multi-creative shape, set `name` on each `creatives[]` entry instead.)" }
-                tracking:
-                  type: object
-                  description: "Meta only. Attaches pixel measurement to the ad regardless of the optimization goal (the \"Website events\" tracking row in Ads Manager). `pixelId` becomes the ad's `tracking_specs` (offsite_conversion + fb_pixel); `urlTags` becomes the ad's `url_tags` (click-tracking query params). Applied on the legacy single-creative shape, every ad of the multi-creative shape, and the attach shape. NOTE: tracking lives on the AD object and is not inherited from the ad set, so pass it on EVERY attach call that should carry the pixel."
-                  properties:
-                    pixelId: { type: string, description: "Meta Pixel ID to attach for offsite-conversion measurement." }
-                    urlTags:
-                      type: array
-                      description: "Click-URL params appended to the ad's destination as `url_tags` (e.g. utm_source). Meta dynamic macros ({{ad.id}}, {{campaign.id}}, {{placement}}, ...) are sent through unescaped so Meta expands them; every other character is percent-encoded."
-                      items:
-                        type: object
-                        required: [key, value]
-                        properties:
-                          key: { type: string }
-                          value: { type: string }
+                tracking: { $ref: '#/components/schemas/AdTracking' }
                 goal:
                   type: string
                   enum: [engagement, traffic, awareness, video_views, lead_generation, lead_conversion, conversions, app_promotion, catalog_sales, page_likes, job_applicants]
@@ -47975,7 +50174,7 @@ paths:
                   description: "Meta only. Multi-advertiser ads: whether Meta may show this ad alongside other advertisers' in one unit. Meta auto-enrols since Aug 2024, so send OPT_OUT to leave. It is a top-level creative field, NOT a `creativeFeatures` key, and Meta rejects it there."
                 validateOnly:
                   type: boolean
-                  description: 'Meta only, single standalone shape only (no creatives[], adSetId, or RESERVED). Dry-run: each node runs Meta''s execution_options validate_only and NOTHING is created or persisted. Children need real parents, so a fresh tree validates the campaign + creative (the ad set needs its campaign to exist, so pass existingCampaignId to validate it too; the ad itself is never validatable pre-create). A Meta validation failure returns the 400 verbatim; success returns 200 with per-node results instead of an ad.'
+                  description: 'Meta only. Validates the complete inline campaign, ad set, creative and ad with execution_options validate_only. Nothing is uploaded or created, and validation bypasses Idempotency-Key storage. Supports a single image, existing video.id or existingCreativeId; media pools, new video uploads, creatives[], adSetId and RESERVED buying return 400. Existing campaign or creative nodes are marked skipped. Success returns 200 with per-node results; Meta rejection returns an error.'
                 budgetAmount: { type: number, description: "Budget in WHOLE currency units (USD: 50 = $50.00), NOT cents. Meta's own Marketing API takes this same number in minor units, so it is an easy and expensive mix-up. Required on legacy + multi-creative shapes. Inherited on attach. OpenAI Ads requires a $1 minimum (its budget is lifetime-only, see budgetType)." }
                 budgetType: { type: string, enum: [daily, lifetime], description: "Required on legacy + multi-creative shapes. Inherited on attach. OpenAI Ads accepts lifetime only (no daily-budget concept on the platform); sending daily returns 422. OpenAI Ads lifetime budgets require `endDate` to give the lifetime cap a spend window." }
                 status:
@@ -48616,8 +50815,28 @@ paths:
                 keywords: { type: array, maxItems: 1000, items: { $ref: '#/components/schemas/KeywordEntry' }, description: "Google Search only. Keywords on the new ad group; entries are strings (BROAD) or { text, matchType }. Editable later via PUT /v1/ads/{adId} targeting.keywords." }
                 negativeKeywords: { type: array, maxItems: 1000, items: { $ref: '#/components/schemas/KeywordEntry' }, description: "Google Search only; other platforms return 400. Ad-group-level negative keywords on the new ad group. Editable later via PUT /v1/ads/{adId} targeting.negativeKeywords." }
                 campaignNegativeKeywords: { type: array, maxItems: 1000, items: { $ref: '#/components/schemas/KeywordEntry' }, description: "Google Search only; other platforms return 400. Campaign-level negative keywords (campaign_criterion.negative), created alongside the ad group. Editable later via PUT /v1/ads/campaigns/{campaignId}/negative-keywords." }
-                additionalHeadlines: { type: array, items: { type: string }, description: "Google Search RSA only. Extra headlines." }
-                additionalDescriptions: { type: array, items: { type: string }, description: "Google Search RSA only. Extra descriptions." }
+                additionalHeadlines:
+                  type: array
+                  items:
+                    oneOf:
+                    - type: string
+                    - $ref: '#/components/schemas/GoogleRsaHeadline'
+                  description: "Google Search RSA only. Extra text assets as strings or objects with text and optional pinnedField. Existing string input remains supported. The effective create lists, including primary text and deduplication, must contain 3-15 headlines and 2-4 descriptions; excess entries return 400."
+                  example:
+                  - Schedule Your Posts
+                  - text: Build With Zernio
+                    pinnedField: HEADLINE_2
+                additionalDescriptions:
+                  type: array
+                  items:
+                    oneOf:
+                    - type: string
+                    - $ref: '#/components/schemas/GoogleRsaDescription'
+                  description: "Google Search RSA only. Extra text assets as strings or objects with text and optional pinnedField. Existing string input remains supported. The effective create lists, including primary text and deduplication, must contain 3-15 headlines and 2-4 descriptions; excess entries return 400."
+                  example:
+                  - Build social publishing into your application.
+                  - text: Connect social accounts with one API.
+                    pinnedField: DESCRIPTION_2
                 sitelinks:
                   type: array
                   minItems: 2
@@ -48852,124 +51071,70 @@ paths:
                     omitted); TikTok automates delivery within it.
                     The budget lives on the Smart+ campaign (Campaign Budget Optimization); a `lifetime`
                     budget additionally requires `endDate`. Cannot be combined with `adSetId`.
+                userOs:
+                  type: array
+                  minItems: 1
+                  items: { type: string, minLength: 1 }
+                  description: 'Meta only. Operating systems and version ranges, such as iOS_ver_14.0_and_above or Android. Emitted as user_os. May also be supplied inside targeting.'
+                userDevice:
+                  type: array
+                  minItems: 1
+                  items: { type: string, minLength: 1 }
+                  description: 'Meta only. Device models such as iPhone. Emitted as user_device. May also be supplied inside targeting.'
+                isSkadnetworkAttribution:
+                  type: boolean
+                  description: 'Meta app promotion only. Immutable campaign flag. Set true for iOS 14+ SKAdNetwork campaigns and supply promotedObject.applicationId plus promotedObject.objectStoreUrl. The campaign receives promotedObject only when this flag is true. Cannot be changed on an existing campaign.'
+                campaignAttribution:
+                  type: string
+                  enum: [AEM, SKADNETWORK]
+                  description: 'Meta ad-set attribution. Required as SKADNETWORK for iOS 14+ app promotion or a SKAdNetwork campaign. Requires AUCTION buying. Standalone Meta ad-set creation is not supported; use this field on /v1/ads/create.'
                 promotedObject:
-                  type: object
-                  description: |
-                    What the ad optimises against. Behaviour depends on the platform.
-
-                    **Meta**: forwarded to the ad set's `promoted_object` (snake-cased).
-                    Required for goals whose ad-set optimization_goal points at a specific
-                    event/page/app (without it Meta rejects the ad-set create with
-                    `error_subcode: 1815430` "Please select a promoted object for your ad set"):
-                      - `goal: conversions` / `lead_conversion` (OFFSITE_CONVERSIONS): requires `pixelId` + `customEventType`, or `customConversionId` when optimising against a Custom Conversion (the conversion carries its own event definition). For a pixel CUSTOM event (one you named yourself in CAPI/Events Manager), send `customEventType: OTHER` + `customEventStr` with the event name.
-                      - `goal: app_promotion` (APP_INSTALLS): requires `applicationId` + `objectStoreUrl`
-                      - `goal: lead_generation` (LEAD_GENERATION): `pageId` is auto-filled from the connected Page when omitted
-
-                    Other Meta goals (engagement, traffic, awareness, video_views) ignore this field.
-
-                    **TikTok**: used by `goal: conversions` and the Smart+ goals (`smartPlus: true`).
-                      - `pixelId` maps to the ad group's `pixel_id`. Required: a TikTok website-conversion
-                        ad group without a pixel is rejected with `40002: Please select a pixel`.
-                      - `customEventType` maps to the ad group's `optimization_event` (the pixel event to
-                        optimise for). Optional on the regular conversions flow, required on Smart+.
-                        See the `customEventType` field below for the valid TikTok codes.
-                      - `applicationId` (Smart+ `goal: app_promotion` only) maps to the ad group's `app_id`:
-                        the App ID of an app registered on the TikTok Ads account (Assets → Events →
-                        App Events). Install optimization needs the app's MMP tracking configured.
-
-                    The remaining `promotedObject.*` fields are Meta-only. Platforms other than
-                    Meta and TikTok ignore `promotedObject` entirely.
-                  properties:
-                    pixelId:
-                      type: string
-                      description: |
-                        Pixel ID. **Meta:** Facebook Pixel ID, required for `goal: conversions`.
-                        Requires `customEventType` alongside it; Meta rejects any promoted_object
-                        carrying `pixel_id` without `custom_event_type` (error_subcode 1885014),
-                        even when `customConversionId` is also present.
-                        **TikTok:** TikTok Pixel ID, required for `goal: conversions`.
-                        To discover the pixels an ad account can use, call
-                        `GET /v1/accounts/{accountId}/tracking-tags?adAccountId=act_...` (each entry
-                        carries `kind` and `ownerAdAccountId`), or
-                        `GET /v1/accounts/{accountId}/conversion-destinations`. Note this is a
-                        different resource from `GET /v1/ads/{adId}/tracking-tags`, which reads an
-                        ad's click-URL params (`url_tags`), not pixels.
-                    customEventType:
-                      type: string
-                      description: |
-                        The event the campaign/ad group optimises against.
-
-                        **Meta:** standard event like `PURCHASE`, `LEAD`, `COMPLETE_REGISTRATION`,
-                        `ADD_TO_CART`. Uppercased internally so callers can pass any case. Required
-                        for `goal: conversions`.
-
-                        **TikTok:** an `optimization_event` code (UPPER_SNAKE, not Meta's vocabulary
-                        and not PascalCase), OR the exact event name shown in TikTok Events Manager
-                        (auto-resolved to its code). Must be one of the event types your TikTok
-                        Pixel tracks; custom events are not optimizable. Current taxonomy:
-                        `SHOPPING` (Purchase), `ON_WEB_CART` (Add to Cart), `INITIATE_ORDER`
-                        (Initiate Checkout), `FORM` (Lead), `ON_WEB_REGISTER` (Complete
-                        Registration), `ON_WEB_DETAIL` (View Content). `ON_WEB_ORDER` is
-                        deprecated. On rejection the error lists the event types your pixel
-                        actually tracks. Optional for `goal: conversions`.
-                    customEventStr:
-                      type: string
-                      description: |
-                        Meta only. Pixel custom-event name to optimise against (Meta's
-                        `custom_event_str`), exactly as it appears in Events Manager and in your
-                        CAPI payloads (case-sensitive, not uppercased). Requires
-                        `customEventType: OTHER`, and `OTHER` requires this field (400 either way).
-                        The same as picking a custom event in Ads Manager's conversion-event
-                        dropdown. For rule-based Custom Conversions use `customConversionId`
-                        instead.
-                    pageId:
-                      type: string
-                      description: |
-                        Facebook Page ID. Used by `goal: lead_generation`. Auto-filled from the
-                        connected Page when omitted.
-                    applicationId:
-                      type: string
-                      description: "App ID. Required for `goal: app_promotion`."
-                    objectStoreUrl:
-                      type: string
-                      format: uri
-                      description: "App Store / Play Store listing URL. Required for `goal: app_promotion`."
-                    customConversionId:
-                      type: string
-                      description: |
-                        Custom Conversion ID, when optimising against one instead of a standard
-                        event. Accepted alone by this API, without `pixelId` or `customEventType`.
-                        If `pixelId` is also sent, `customEventType` is still required on the
-                        promoted_object (Meta rejects `pixel_id` without `custom_event_type`,
-                        error_subcode 1885014).
-                    productCatalogId:
-                      type: string
-                      description: "Optional catalog ID. If supplied with productSetId, the set must belong to this catalog. A catalog ID cannot replace productSetId."
-                    productSetId:
-                      type: string
-                      description: "Meta product SET ID from GET /v1/ads/catalogs/{catalogId}/product-sets. Zernio checks that the token can read the set and its product_catalog before creation. A catalog ID or inaccessible set returns a precise 400 naming promotedObject.productSetId. A mismatch with productCatalogId names promotedObject.productCatalogId."
-                    offlineConversionDataSetId:
-                      type: string
-                      description: 'Meta only. Offline event set (dataset) to optimise toward. Post-merger these are datasets: the id is the dataset id (for pixel-backed datasets, the pixel id).'
-                    whatsappPhoneNumber:
-                      type: string
-                      description: 'Meta only. WhatsApp number on messaging-destination ad sets.'
-                  additionalProperties: false
-            example:
-              accountId: '69fc524892b3d8e85f893e73'
-              adAccountId: act_123456789
-              name: Autumn promotion
-              goal: traffic
-              budgetAmount: 5
-              budgetType: daily
-              status: PAUSED
-              headline: Save on your next order
-              body: Use SAVE20 at checkout.
-              callToAction: SHOP_NOW
-              linkUrl: https://example.com/shop
-              imageUrl: https://example.com/ad.jpg
-              promotion: { type: PERCENTAGE_OFF, value: 20, code: SAVE20 }
-              creativeFeatures: { auto_promotion_tag: OPT_OUT }
+                  $ref: '#/components/schemas/AdPromotedObject'
+            examples:
+              appPromotion:
+                value:
+                  accountId: '69fc524892b3d8e85f893e73'
+                  adAccountId: 'act_757082720485182'
+                  name: 'iOS app installs'
+                  goal: app_promotion
+                  isSkadnetworkAttribution: true
+                  campaignAttribution: SKADNETWORK
+                  buyingType: AUCTION
+                  billingEvent: IMPRESSIONS
+                  optimizationGoal: APP_INSTALLS
+                  promotedObject:
+                    applicationId: '123456789'
+                    objectStoreUrl: 'https://apps.apple.com/us/app/id123456789'
+                  linkUrl: 'https://apps.apple.com/us/app/id123456789'
+                  headline: 'Install our app'
+                  body: 'Get started today.'
+                  callToAction: INSTALL_MOBILE_APP
+                  imageUrl: 'https://example.com/app.jpg'
+                  targeting:
+                    countries: [US]
+                    userOs: [iOS_ver_14.0_and_above]
+                  tracking:
+                    urlTags: [{ key: utm_content, value: '{{ad.id}}' }]
+                  budgetAmount: 1
+                  budgetType: daily
+                  status: PAUSED
+                  validateOnly: true
+              retailPromotion:
+                value:
+                  accountId: '69fc524892b3d8e85f893e73'
+                  adAccountId: act_123456789
+                  name: Autumn promotion
+                  goal: traffic
+                  budgetAmount: 5
+                  budgetType: daily
+                  status: PAUSED
+                  headline: Save on your next order
+                  body: Use SAVE20 at checkout.
+                  callToAction: SHOP_NOW
+                  linkUrl: https://example.com/shop
+                  imageUrl: https://example.com/ad.jpg
+                  promotion: { type: PERCENTAGE_OFF, value: 20, code: SAVE20 }
+                  creativeFeatures: { auto_promotion_tag: OPT_OUT }
       responses:
         '200':
           description: 'validateOnly dry-run passed, nothing was created'