late-sdk 0.0.900 → 0.0.902

data/openapi.yaml

@@ -148,13 +148,13 @@ x-documentation:
     Receive real-time notifications for post status changes, account events, and incoming messages:
 
     - `post.scheduled` - Post entered the scheduled state: created with a schedule, added to a queue, a draft promoted to scheduled or queued, a failed post retried, or a recycled clone created
-    - `post.published` - Post successfully published
-    - `post.failed` - Post failed on all platforms
-    - `post.partial` - Post published to some platforms, failed on others
+    - `post.published` - Post successfully published. If a platform target later fails background reconciliation, the post is re-rolled up and a `post.failed` or `post.partial` follows for the same post.
+    - `post.failed` - Post failed on all platforms. Can follow an earlier `post.published` for the same post when background reconciliation discovers the publish never actually completed.
+    - `post.partial` - Post published to some platforms, failed on others. Can follow an earlier `post.published` for the same post when background reconciliation discovers one target's publish never actually completed.
     - `post.cancelled` - Post publishing was cancelled
     - `post.recycled` - Post recycled (cloned and re-scheduled)
-    - `post.platform.published` - A single platform target inside a post finished publishing successfully. Fires once per platform-account as it terminates, without waiting for other platforms on the same post. Use this for incremental UIs; use `post.published` for the post-level rollup.
-    - `post.platform.failed` - A single platform target inside a post failed permanently. Temporary/retryable failures do NOT fire this event, only permanent ones, so retry loops stay quiet.
+    - `post.platform.published` - A single platform target inside a post finished publishing successfully. Fires once per platform-account as it terminates, without waiting for other platforms on the same post. Use this for incremental UIs; use `post.published` for the post-level rollup. A target that later fails background reconciliation (e.g. a Facebook video Meta accepted but never actually published) emits `post.platform.failed` afterward for the same target.
+    - `post.platform.failed` - A single platform target inside a post failed permanently. Temporary/retryable failures do NOT fire this event, only permanent ones, so retry loops stay quiet. Can fire after this same target already emitted `post.platform.published`, when background reconciliation later discovers the publish never actually completed on the platform's side.
     - `post.platform.deleted` - A single platform target inside a post was detected as deleted on the platform after publishing (e.g. the user deleted the Instagram post natively). Detection is poll-driven via Zernio background sync (~hourly), not real-time. `platform.deletedAt` carries the detection time. Coverage is bounded to the posts the platform listing returns.
     - `post.tiktok.url_resolved` - A published TikTok post's public URL became available. TikTok exposes the numeric video id asynchronously, so `post.published` / `post.platform.published` can carry an empty `publishedUrl` for TikTok; this event delivers the URL once resolved (at most once per platform target). Never fires for drafts or private posts, which have no public URL.
     - `post.external.created` - A native post authored outside Zernio (e.g. a Google Business Profile localPost created in the Google UI) was detected by our sync for the first time. Poll-driven (~hourly), not real-time. Payload carries `post.source: "external"`.
@@ -2724,8 +2724,11 @@ components:
         and for `post.tiktok.url_resolved` (same shape, fired when a
         published TikTok post's public URL is backfilled). Terminal events
         fire once per platform target inside a post as that platform
-        reaches a terminal state (published or permanent failure). The
-        `post` envelope mirrors the shape of `WebhookPayloadPost` so
+        reaches a terminal state (published or permanent failure), except
+        that a target which later fails background reconciliation emits
+        `post.platform.failed` a second time, after its own
+        `post.platform.published`. The `post` envelope mirrors the shape
+        of `WebhookPayloadPost` so
         consumers can reuse rendering logic; the `platform` block
         identifies which specific platform transitioned; the `account`
         block identifies the connected account behind that
@@ -9175,6 +9178,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:
@@ -9331,6 +9463,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." }
@@ -10365,7 +10518,10 @@ webhooks:
         consumers building incremental UIs get notified immediately, even
         when other platforms on the same post are still processing.
         The envelope event (`post.published` / `post.partial`) fires
-        separately AFTER all platforms have terminated.
+        separately AFTER all platforms have terminated. A target that later
+        fails background reconciliation (e.g. a Facebook video Meta accepted
+        but never actually published) emits `post.platform.failed` for the
+        same target afterward.
       tags: [Webhook Events]
       requestBody:
         required: true
@@ -10385,7 +10541,9 @@ webhooks:
         permanently. Temporary/retryable failures do NOT fire this event,
         only permanent ones do, so retry loops stay quiet. The envelope event
         (`post.failed` / `post.partial`) fires separately AFTER all
-        platforms have terminated.
+        platforms have terminated. Can also fire a second time for a target
+        that already emitted `post.platform.published`, if background
+        reconciliation later discovers the publish never actually completed.
       tags: [Webhook Events]
       requestBody:
         required: true
@@ -44491,6 +44649,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)
@@ -44523,10 +44686,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' }
@@ -44549,7 +44728,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),
@@ -44592,9 +44775,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
@@ -44702,10 +44927,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
@@ -44796,322 +45017,977 @@ 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' }
+                  campaignId:
+                    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: '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.
+          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 }, 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.
+      - 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
+              - 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: 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'
+          description: "Assets returned."
           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.' }
+                type: object
+                properties:
+                  updated:
+                    type: integer
         '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."
+    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: 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
+              - assetResourceNames
+              - campaignAssetResourceNames
               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."
+                assetResourceNames:
                   type: array
+                  items:
+                    type: string
                   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."
+                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:
-                  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) }
+                  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}/preview:
+  /v1/ads/ad-sets/{adSetId}/assets:
     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.
+      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)." }
-        - { 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: 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: Rendered previews
+          description: "Assets returned."
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  adId: { type: string }
-                  previews:
+                  adGroupId:
+                    type: string
+                  sitelinks:
                     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:
+                        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:
-                        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." }
-        '400': { description: "Invalid input" }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '404': { description: Ad not found }
-        '422': { description: No active Meta connection for this ad. Reconnect the account. }
-        '501': { description: Only supported on Meta (facebook/instagram) }
-
-  /v1/ads/keywords/ideas:
+                        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:
-      x-resource-group: "ads"
-      operationId: generateKeywordIdeas
-      tags: ["Ad Insights"]
-      x-platforms: ["google"]
-      summary: Generate keyword ideas (Google Keyword Planner)
-      description: |
-        Google Ads only. Runs Keyword Planner's generateKeywordIdeas from seed keywords, a seed URL,
-        or both, returning idea rows verbatim (avgMonthlySearches, competition, competitionIndex,
-        top-of-page bid micros, monthlySearchVolumes). Counters are int64s encoded as strings; bid
+      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." }
+        '400': { description: "Invalid input" }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { description: Ad not found }
+        '422': { description: No active Meta connection for this ad. Reconnect the account. }
+        '501': { description: Only supported on Meta (facebook/instagram) }
+
+  /v1/ads/keywords/ideas:
+    post:
+      x-resource-group: "ads"
+      operationId: generateKeywordIdeas
+      tags: ["Ad Insights"]
+      x-platforms: ["google"]
+      summary: Generate keyword ideas (Google Keyword Planner)
+      description: |
+        Google Ads only. Runs Keyword Planner's generateKeywordIdeas from seed keywords, a seed URL,
+        or both, returning idea rows verbatim (avgMonthlySearches, competition, competitionIndex,
+        top-of-page bid micros, monthlySearchVolumes). Counters are int64s encoded as strings; bid
         values are micros of the account currency. Omitting `countries` targets worldwide.
       security:
         - bearerAuth: []
@@ -47671,141 +48547,943 @@ paths:
 
   /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.
+      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: []
+      - 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." }
+      - 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: Account-level callouts
+          description: "Assets returned."
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  customerId: { type: string }
+                  customerId:
+                    type: string
                   callouts:
                     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
+                        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 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 }
-
+          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: 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.
+      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: []
+      - bearerAuth: []
       requestBody:
         required: true
         content:
           application/json:
             schema:
               type: object
-              required: [accountId, callouts]
+              required:
+              - accountId
+              - callouts
               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." }
+                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
-                  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'
+              callouts:
+              - Fast setup
       responses:
         '201':
-          description: Callouts created
+          description: "Assets created and attached."
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  customerId: { type: string }
+                  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' }
+                        assetId:
+                          type: string
+                        text:
+                          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."
+    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:
-      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.
+      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: []
+      - 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/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
+                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: removeAccountSitelink
+      summary: Remove account sitelink
+      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/structured-snippets:
+    get:
+      operationId: listAccountStructuredSnippets
+      summary: List account snippets
+      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
+                  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: "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: addAccountStructuredSnippets
+      summary: Add account snippets
+      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
+              - structuredSnippets
+              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."
+                structuredSnippets:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/GoogleStructuredSnippet'
+                  minItems: 1
+                  maxItems: 20
+            example:
+              accountId: 64b1f0c8a1b2c3d4e5f60718
+              customerId: '1234567890'
+              structuredSnippets:
+              - header: Types
+                values:
+                - Scheduling
+                - Analytics
+                - Messaging
+      responses:
+        '201':
+          description: "Assets created and attached."
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  customerId:
+                    type: string
+                  structuredSnippets:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        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 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: []
+      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."
+                      structuredSnippetAsset:
+                        $ref: '#/components/schemas/GoogleStructuredSnippet'
+                    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
+                structuredSnippetAsset:
+                  header: Types
+                  values:
+                  - Scheduling
+                  - Reporting
+                  - Messaging
+      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: 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: []
+      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/finance:
     get:
@@ -49145,8 +50823,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