late-sdk 0.0.716 → 0.0.718

data/openapi.yaml

@@ -150,21 +150,23 @@ x-documentation:
     - `account.connected` - Social account connected
     - `account.disconnected` - Social account disconnected (token expired)
     - `account.ads.initial_sync_completed` - Initial ads sync (discovery + 90-day backfill) completed for an ads-enabled account
-    - `message.received` - New DM received
-    - `conversation.started` - A new conversation opened between one of your accounts and a contact, in either direction (any DM platform); fires only the first time the thread appears
+    - `message.received` - New inbound DM or SMS received (SMS arrives with `platform: "sms"`)
+    - `conversation.started` - A new conversation opened between one of your accounts and a contact, in either direction (any DM platform, and SMS); fires only the first time the thread appears
     - `message.sent` - DM sent via the API
     - `message.edited` - A sender edited a message (Instagram, Messenger, Telegram)
     - `message.deleted` - A sender deleted ("unsent") a message (Instagram; WhatsApp when the business deletes a sent message)
-    - `message.delivered` - An outgoing message was delivered (WhatsApp, Messenger)
+    - `message.delivered` - An outgoing message was delivered (WhatsApp, Messenger, SMS)
     - `message.read` - An outgoing message was read by the recipient (WhatsApp, Messenger, Instagram)
-    - `message.failed` - An outgoing message failed delivery (WhatsApp)
+    - `message.failed` - An outgoing message failed delivery (WhatsApp, SMS; on SMS the carrier's error code rides in `error`)
     - `reaction.received` - A participant added or removed an emoji reaction on a message (WhatsApp, Telegram, Slack, Instagram, Facebook Messenger)
+    - `referral.received` - Someone opened an existing Instagram/Messenger thread through an ig.me/m.me `ref` link or a returning Messenger ad click; carries Meta's referral object (a referral that rides an inbound message arrives on `message.received` under `metadata.referral` instead)
     - `comment.received` - New comment received on a post
     - `review.new` - New review posted on a connected account (Google Business Profile)
     - `review.updated` - Review updated or reply added (Google Business Profile, or via reply API)
     - `lead.received` - New lead submitted against a Meta Lead Gen (Instant) Form. `lead.fields` is the question-key → answer map; `lead.formId`/`lead.adId` give provenance.
     - `ad.status_changed` - Ad, ad set, or campaign changed status on the ad platform (Meta: `in_process_ad_objects` entry/exit and `with_issues_ad_objects` violations)
     - `whatsapp.template.status_updated` - WhatsApp Business template completed (re)review by Meta. `template.status` carries the new state (APPROVED, REJECTED, PENDING, PAUSED, DISABLED, IN_APPEAL, PENDING_DELETION); `template.reason` is Meta's free-form reason or "NONE".
+    - `whatsapp.template.category_updated` - Meta reclassified a WhatsApp Business template's category (drives tariff and marketing opt-out applicability). `template.changeType` is `scheduled` (24h advance notice) or `applied`; `template.category` is always the category right now.
     - `call.received` - An inbound call (phone/PSTN or WhatsApp) reached one of your numbers and was routed to its destination
     - `call.ended` - A call ended; carries duration, end reason, cost breakdown, and the recording when enabled
     - `call.failed` - A call failed with a hard error before or during bridging
@@ -201,6 +203,12 @@ tags:
   - name: Posts
     description: |
       Create, schedule, list, update, and delete posts across all connected social accounts.
+  - name: Blogs
+    description: |
+      Manage blogs and blog articles on connected accounts. Currently supported
+      for Shopify accounts (scopes read_content and write_content). Blogs are
+      the containers; articles are the posts inside them. All content lives on
+      the platform; Zernio proxies it and stores nothing.
   - name: Users
     description: |
       Read the authenticated user and team members.
@@ -412,7 +420,7 @@ tags:
   - name: Webhooks
     description: |
       Configure webhooks for real-time notifications. Webhooks can be created from the dashboard (Settings → Webhooks) or via this API.
-      Events: post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, post.platform.published, post.platform.failed, post.platform.deleted, post.tiktok.url_resolved, post.external.created, post.external.updated, post.external.deleted, account.connected, account.disconnected, account.ads.initial_sync_completed, message.received, conversation.started, call.received, call.ended, call.failed, call.permission_request, message.sent, message.edited, message.deleted, message.delivered, message.read, message.failed, reaction.received, comment.received, review.new, review.updated, lead.received, ad.status_changed, whatsapp.template.status_updated, whatsapp.automatic_event, whatsapp.number.activated, whatsapp.number.declined, whatsapp.number.action_required, whatsapp.number.verification_required, whatsapp.number.suspended, whatsapp.number.reactivated, whatsapp.number.released, whatsapp.number.kyc_submitted, verification.approved, verification.failed, webhook.test.
+      Events: post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, post.platform.published, post.platform.failed, post.platform.deleted, post.tiktok.url_resolved, post.external.created, post.external.updated, post.external.deleted, account.connected, account.disconnected, account.ads.initial_sync_completed, message.received, conversation.started, call.received, call.ended, call.failed, call.permission_request, message.sent, message.edited, message.deleted, message.delivered, message.read, message.failed, reaction.received, referral.received, comment.received, review.new, review.updated, lead.received, ad.status_changed, whatsapp.template.status_updated, whatsapp.template.category_updated, whatsapp.automatic_event, whatsapp.number.activated, whatsapp.number.declined, whatsapp.number.action_required, whatsapp.number.verification_required, whatsapp.number.suspended, whatsapp.number.reactivated, whatsapp.number.released, whatsapp.number.kyc_submitted, verification.approved, verification.failed, webhook.test.
       Security: optional HMAC-SHA256 signature in X-Zernio-Signature header. Configure a secret key to enable verification. Custom headers supported.
 
       Resource groups. Every event belongs to one group: post.* to publishing, message.*, reaction.*, conversation.*, call.* and whatsapp.automatic_event to messages, comment.* and review.* to engagement, lead.* to contacts, ad.* to ads, account.* and whatsapp.template.* to accounts, whatsapp.number.* and verification.* to telephony, webhook.test to webhooks. Two independent controls use that mapping. (1) A restricted (zrk_) API key can only subscribe to, test-fire, redeliver, or read delivery logs for events in the groups it holds, so it can never create a subscription broader than itself. (2) Each subscription carries its own `disabledResourceGroups` denylist: events in a disabled group are dropped before delivery to that endpoint, on live delivery and on every replay path, no matter which key or session created the subscription. Changing that denylist applies to every event emitted after the change; events already queued when it landed can still be delivered for up to five minutes after they were enqueued, because the delivery worker trusts a five-minute enqueue-time snapshot before re-checking. Absent or empty on a subscription means it receives everything it subscribes to, which is the behavior of every subscription created before the field existed.
@@ -892,8 +900,11 @@ components:
           maxLength: 3
           description: |
             ISO 4217 currency code matching the ad account's currency
-            (e.g. `USD`). Optional; Meta infers from the ad account
-            when omitted.
+            (e.g. `USD`). Optional: Zernio resolves it from the ad account
+            when omitted. The value selects the minor-unit exponent Zernio
+            converts budget/bid amounts by before calling Meta (most
+            currencies are cents; zero-decimal currencies like JPY/KRW are
+            sent as-is).
         endDate:
           type: string
           format: date-time
@@ -1197,6 +1208,11 @@ components:
           properties:
             x: { type: number }
             y: { type: number }
+        label:
+          type: string
+          minLength: 1
+          maxLength: 80
+          description: 'Optional display name shown on the builder canvas and inspector, falling back to the node type when absent. The nodes array is replaced wholesale on update, so it must be resent to be kept.'
     WorkflowEdge:
       type: object
       required: [id, source, target]
@@ -1352,9 +1368,6 @@ components:
         mediaType:
           type: string
           description: Media type (e.g. image, video, carousel)
-        mediaUrl:
-          type: string
-          description: Primary media URL
         thumbnailUrl:
           type: string
           description: Thumbnail URL
@@ -1381,7 +1394,7 @@ components:
             views: { type: integer }
             reach: { type: integer }
             impressions: { type: integer }
-            engagementRate: { type: number }
+            engagementRate: { type: number, description: 'Percentage, rounded to 2 decimals. Same definition as PostAnalytics.engagementRate: (likes + comments + shares + saves) / (impressions or reach or views) * 100, where the denominator is the first of the three that is non-zero. Clicks and follows are never counted.' }
             lastUpdated: { type: string, format: date-time, description: When these metrics were last refreshed }
     ErrorResponse:
       type: object
@@ -1943,7 +1956,7 @@ components:
           description: 'Present only when the range reaches into YouTube''s ~3-day processing window: the first date whose numbers are provisional and may still be revised by YouTube.'
         retentionCurve:
           type: array
-          description: Up to 100 points covering the video timeline, aggregated over the date range. Empty for videos with very few views.
+          description: 'Up to 100 points covering the video timeline, aggregated over the date range. Can be empty when YouTube has no retention data for the video in the given range.'
           items:
             type: object
             properties:
@@ -1958,10 +1971,10 @@ components:
                 description: Retention vs videos of similar length (0 = worst, 0.5 = median, 1 = best)
               startedWatching:
                 type: integer
-                description: Viewers who started watching in this segment
+                description: 'Viewers who started watching in this segment. 0 when YouTube has no segment-level data for the video.'
               stoppedWatching:
                 type: integer
-                description: Viewers who stopped watching in this segment
+                description: 'Viewers who stopped watching in this segment. 0 when YouTube has no segment-level data for the video.'
               totalSegmentImpressions:
                 type: integer
                 description: Total views of this segment, including rewatches
@@ -2325,7 +2338,7 @@ components:
           type: array
           items:
             type: string
-            enum: [post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, post.platform.published, post.platform.failed, post.platform.deleted, post.tiktok.url_resolved, post.external.created, post.external.updated, post.external.deleted, account.connected, account.disconnected, account.ads.initial_sync_completed, message.received, conversation.started, call.received, call.ended, call.failed, call.permission_request, message.sent, message.edited, message.deleted, message.delivered, message.read, message.failed, reaction.received, comment.received, review.new, review.updated, lead.received, ad.status_changed, whatsapp.template.status_updated, whatsapp.automatic_event, whatsapp.number.activated, whatsapp.number.declined, whatsapp.number.action_required, whatsapp.number.verification_required, whatsapp.number.suspended, whatsapp.number.reactivated, whatsapp.number.released, whatsapp.number.kyc_submitted, verification.approved, verification.failed]
+            enum: [post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, post.platform.published, post.platform.failed, post.platform.deleted, post.tiktok.url_resolved, post.external.created, post.external.updated, post.external.deleted, account.connected, account.disconnected, account.ads.initial_sync_completed, message.received, conversation.started, call.received, call.ended, call.failed, call.permission_request, message.sent, message.edited, message.deleted, message.delivered, message.read, message.failed, reaction.received, referral.received, comment.received, review.new, review.updated, lead.received, ad.status_changed, whatsapp.template.status_updated, whatsapp.template.category_updated, whatsapp.automatic_event, whatsapp.number.activated, whatsapp.number.declined, whatsapp.number.action_required, whatsapp.number.verification_required, whatsapp.number.suspended, whatsapp.number.reactivated, whatsapp.number.released, whatsapp.number.kyc_submitted, verification.approved, verification.failed]
           description: Events subscribed to
         isActive:
           type: boolean
@@ -2462,6 +2475,7 @@ components:
         timestamp:
           type: string
           format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadPostPlatform:
       type: object
       description: |
@@ -2554,6 +2568,7 @@ components:
         timestamp:
           type: string
           format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadAccountConnected:
       type: object
       description: Webhook payload for account connected events
@@ -2584,6 +2599,7 @@ components:
         timestamp:
           type: string
           format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadAccountDisconnected:
       type: object
       description: Webhook payload for account disconnected events
@@ -2621,6 +2637,7 @@ components:
         timestamp:
           type: string
           format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadAccountAdsInitialSyncCompleted:
       type: object
       description: |
@@ -2723,6 +2740,7 @@ components:
         timestamp:
           type: string
           format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadComment:
       type: object
       description: Webhook payload for comment received events (Instagram, Facebook, Twitter/X, YouTube, LinkedIn, Bluesky, Reddit)
@@ -2766,6 +2784,9 @@ components:
                   type: string
                 picture:
                   type: [string, "null"]
+                isOwnAccount:
+                  type: boolean
+                  description: 'True when this comment was authored by the connected account itself (Meta re-delivers the account''s own replies as comments events). Populated on the Instagram and Facebook realtime webhooks only; absent means not evaluated, never "not the account".'
                 instagramProfile:
                   type: object
                   description: |
@@ -2867,6 +2888,7 @@ components:
         timestamp:
           type: string
           format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadLead:
       type: object
       description: Webhook payload for lead.received events (Meta Lead Gen / Instant Forms).
@@ -2931,6 +2953,7 @@ components:
         timestamp:
           type: string
           format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     ReviewWebhookReview:
       type: object
       description: Review data shared by review.new and review.updated payloads.
@@ -3007,6 +3030,7 @@ components:
         timestamp:
           type: string
           format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadReviewUpdated:
       type: object
       description: |
@@ -3040,6 +3064,7 @@ components:
         timestamp:
           type: string
           format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     ExternalPostWebhookPost:
       type: object
       description: Native (external) post data shared by all post.external.* payloads.
@@ -3114,6 +3139,7 @@ components:
         timestamp:
           type: string
           format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     # ─── Shared sub-schemas for inbox lifecycle webhook payloads ────────────
     # WebhookPayloadMessageEdited / Deleted / DeliveryStatus reference these
     # as $refs. They were added as top-level named schemas (rather than nested
@@ -3133,7 +3159,7 @@ components:
           description: Internal conversation ID
         platform:
           type: string
-          enum: [instagram, facebook, telegram, whatsapp]
+          enum: [instagram, facebook, telegram, whatsapp, sms]
         platformMessageId:
           type: string
           description: Platform's message ID
@@ -3303,7 +3329,7 @@ components:
             sender:
               type: object
               required: [id]
-              description: 'Whoever added or removed the reaction. Usually the participant, but on Slack, Instagram and Facebook Messenger it is the business own platform id when the reaction was made from the native app: compare it with conversation.participantId.'
+              description: 'Whoever added or removed the reaction. Usually the participant, but on WhatsApp, Slack, Instagram and Facebook Messenger it is the business own platform id when the business reacted from the native app or via the reactions API: compare it with conversation.participantId.'
               properties:
                 id:
                   type: string
@@ -3329,6 +3355,77 @@ components:
         timestamp:
           type: string
           format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
+    # ────────────────────────────────────────────────────────────────────────
+    WebhookPayloadReferral:
+      type: object
+      description: 'Webhook payload for referral received events (Instagram, Facebook Messenger)'
+      required: [id, event, referral, sender, conversation, account, timestamp]
+      properties:
+        id:
+          type: string
+          description: Stable webhook event ID
+        event:
+          type: string
+          enum: [referral.received]
+        referral:
+          type: object
+          description: |
+            Meta's referral object, forwarded verbatim. Same shape as
+            `metadata.referral` on `message.received`: `ref` + `source` for
+            ig.me / m.me links, `ad_id` + `ads_context_data` for returning
+            Messenger ad clicks.
+          properties:
+            ref:
+              type: string
+              description: The `ref` parameter of the clicked ig.me / m.me link or ad.
+            source:
+              type: string
+              description: 'Meta-supplied source (`SHORTLINK`, `SHORTLINKS`, `IGME-SOURCE-LINK`, `ADS` - treat as opaque).'
+            type:
+              type: string
+              description: Meta-supplied referral type (e.g. `OPEN_THREAD`).
+            referer_uri:
+              type: string
+              description: URI of the originating site, when Meta supplies one. Facebook Messenger only.
+            ad_id:
+              type: string
+              description: The Meta ad ID, on returning ad clicks. Facebook Messenger only.
+            ads_context_data:
+              type: object
+              description: Snapshot of the ad's public context at click time.
+              properties:
+                ad_title:
+                  type: string
+                photo_url:
+                  type: string
+                video_url:
+                  type: string
+                post_id:
+                  type: string
+                product_id:
+                  type: string
+                flow_id:
+                  type: string
+        sender:
+          type: object
+          required: [id]
+          description: Who clicked - the conversation participant.
+          properties:
+            id:
+              type: string
+              description: Platform-scoped user ID (IGSID / PSID).
+            contactId:
+              type: string
+              description: Zernio CRM Contact id for this sender, when one exists.
+        conversation:
+          $ref: '#/components/schemas/InboxWebhookConversation'
+        account:
+          $ref: '#/components/schemas/InboxWebhookAccount'
+        timestamp:
+          type: string
+          format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     # ────────────────────────────────────────────────────────────────────────
     WebhookPayloadMessage:
       type: object
@@ -3353,7 +3450,7 @@ components:
               description: Internal conversation ID
             platform:
               type: string
-              enum: [instagram, facebook, telegram, whatsapp]
+              enum: [instagram, facebook, telegram, whatsapp, sms]
             platformMessageId:
               type: string
               description: Platform's message ID
@@ -3606,17 +3703,27 @@ components:
             referral:
               type: [object, "null"]
               description: |
-                Ad-click attribution forwarded verbatim from Meta. Populated only on
+                Click attribution forwarded verbatim from Meta. Populated only on
                 the FIRST inbound message after the click; absent on subsequent
-                messages of the same conversation.
+                messages of the same conversation. On Instagram and Messenger a
+                RETURNING click also attaches it to the first message that
+                follows, so read it on every `message.received` for per-click
+                attribution; a click that opens an existing thread WITHOUT a
+                message arrives as the separate `referral.received` event.
 
-                The populated subset identifies the source platform:
+                The populated subset identifies the source:
                   - `ctwa_clid` and `source_*` fields: WhatsApp CTWA
                     (Click-to-WhatsApp). Attribution window is 7 days from click.
                     Forward to Meta Conversions API for Business Messaging replay.
                   - `ad_id` and `ads_context_data`: Facebook Messenger CTM
                     (Click-to-Message) or Instagram CTD (Click-to-Direct). Use
                     `ad_id` to attribute the conversation to a specific ad.
+                  - `ref` without `ad_id`: an ig.me / m.me link carrying a
+                    `?ref=` parameter (`source` is `SHORTLINK`, `SHORTLINKS` or
+                    `IGME-SOURCE-LINK` depending on surface - treat it as
+                    opaque). Instagram delivers ig.me refs on new threads only
+                    when the account has at least one Ice Breaker configured
+                    (`PUT /v1/accounts/{accountId}/instagram-ice-breakers`).
               properties:
                 ctwa_clid:
                   type: string
@@ -3647,18 +3754,25 @@ components:
                 ref:
                   type: string
                   description: |
-                    Optional `ref` parameter passed through from the Meta ad
-                    creative. Facebook Messenger CTM / Instagram CTD only.
+                    The `ref` parameter passed through from the Meta ad creative
+                    or from an ig.me / m.me link. Instagram / Facebook Messenger
+                    only.
                 source:
                   type: string
                   description: |
-                    Meta-supplied source identifier (e.g. `ADS`). Facebook Messenger
-                    CTM / Instagram CTD only.
+                    Meta-supplied source identifier (`ADS` for ad clicks;
+                    `SHORTLINK`, `SHORTLINKS` or `IGME-SOURCE-LINK` for ref
+                    links). Instagram / Facebook Messenger only.
                 type:
                   type: string
                   description: |
-                    Meta-supplied referral type (e.g. `OPEN_THREAD`). Facebook
-                    Messenger CTM / Instagram CTD only.
+                    Meta-supplied referral type (e.g. `OPEN_THREAD`). Instagram /
+                    Facebook Messenger only.
+                referer_uri:
+                  type: string
+                  description: |
+                    URI of the originating site, when Meta supplies one (m.me
+                    links opened from the web). Facebook Messenger only.
                 ads_context_data:
                   type: object
                   description: |
@@ -3677,9 +3791,39 @@ components:
                       type: string
                     flow_id:
                       type: string
+            unsupported:
+              type: object
+              description: |
+                WhatsApp only. Meta's own reason this message has no
+                renderable body. Present when Meta attached an error to the
+                inbound payload; in practice the `unsupported`, `errors` and
+                `unknown` types (code 131051: message type currently not
+                supported). `text` on those messages is the fixed
+                `[Unsupported message]` placeholder.
+              properties:
+                code:
+                  type: integer
+                  description: Meta's numeric error code (e.g. 131051).
+                title:
+                  type: string
+                  description: Meta's short error title.
+                details:
+                  type: string
+                  description: Meta's human-readable error detail string.
+            noRenderableContent:
+              type: boolean
+              description: |
+                Instagram / Facebook Messenger only. Set when the message
+                carries nothing an integrator can render (a `template`
+                attachment with no text and no parseable content, or Meta's
+                own `is_unsupported` flag). Sibling of `unsupported` above
+                (WhatsApp only, carries Meta's error code/title/details): this
+                field has no error envelope, just the boolean. Absence means
+                "not flagged", never "checked and renderable".
         timestamp:
           type: string
           format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadMessageSent:
       type: object
       description: Webhook payload for message sent events (fired when a message is sent via the API, or from the WhatsApp Business app on Coexistence numbers)
@@ -3765,6 +3909,7 @@ components:
         timestamp:
           type: string
           format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     InboxMessageEditAttachment:
       type: object
       description: Attachment snapshot inside an edit-history entry.
@@ -3817,7 +3962,10 @@ components:
           $ref: '#/components/schemas/InboxWebhookConversation'
         account:
           $ref: '#/components/schemas/InboxWebhookAccount'
-        timestamp: { type: string, format: date-time }
+        timestamp:
+          type: string
+          format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadMessageDeleted:
       type: object
       description: |
@@ -3843,7 +3991,10 @@ components:
           $ref: '#/components/schemas/InboxWebhookConversation'
         account:
           $ref: '#/components/schemas/InboxWebhookAccount'
-        timestamp: { type: string, format: date-time }
+        timestamp:
+          type: string
+          format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadMessageDeliveryStatus:
       type: object
       description: |
@@ -3852,10 +4003,12 @@ components:
         delivery state for an outgoing message.
 
         Platform support:
-          * message.delivered — WhatsApp, Facebook Messenger.
-          * message.read      — WhatsApp, Facebook Messenger, Instagram.
-          * message.failed    — WhatsApp only (other platforms don't expose
-            per-message failure via webhook).
+          * message.delivered: WhatsApp, Facebook Messenger, SMS.
+          * message.read: WhatsApp, Facebook Messenger, Instagram. Not SMS
+            (carriers report delivery, never read).
+          * message.failed: WhatsApp and SMS (other platforms don't expose
+            per-message failure via webhook). On SMS, `error.code` is the
+            carrier's numeric code and `error.message` its reason.
       required: [id, event, message, statusAt, conversation, account, timestamp]
       properties:
         id: { type: string }
@@ -3886,7 +4039,10 @@ components:
           $ref: '#/components/schemas/InboxWebhookConversation'
         account:
           $ref: '#/components/schemas/InboxWebhookAccount'
-        timestamp: { type: string, format: date-time }
+        timestamp:
+          type: string
+          format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadConversationStarted:
       type: object
       description: |
@@ -3931,7 +4087,10 @@ components:
           type: string
           format: date-time
           description: When the conversation document was created.
-        timestamp: { type: string, format: date-time }
+        timestamp:
+          type: string
+          format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     CallRecord:
       type: object
       description: |
@@ -4027,7 +4186,10 @@ components:
             conversationId: { type: string }
             startedAt: { type: string, format: date-time }
         account: { $ref: '#/components/schemas/InboxWebhookAccount' }
-        timestamp: { type: string, format: date-time }
+        timestamp:
+          type: string
+          format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadCallEnded:
       type: object
       description: |
@@ -4053,6 +4215,8 @@ components:
             endedAt: { type: string, format: date-time }
             durationSeconds: { type: integer }
             endReason: { type: string, enum: [hangup, no_answer, rejected, error] }
+            hangupCause: { type: [string, "null"], description: "Raw carrier hangup cause behind endReason (e.g. normal_clearing, call_rejected, not_found). Null when the carrier reported none." }
+            sipHangupCause: { type: [string, "null"], description: "SIP response code that ended the call when SIP-signalled (e.g. '403', '486', '603'). endReason collapses all three to 'rejected', so this is what separates a refused destination from a busy line. Null on non-SIP legs." }
             recordingUrl: { type: string }
             recordingExpiresAt: { type: string, format: date-time }
             billing:
@@ -4064,7 +4228,10 @@ components:
                 billableCostUSD: { type: number, description: 'The amount Zernio bills you = Telnyx leg + recording. Excludes Meta (billed by Meta directly).' }
                 totalCostUSD: { type: number, description: 'Full economic cost incl. the Meta portion you pay directly (Meta + Telnyx + recording). Display only, not the Zernio-billed amount.' }
         account: { $ref: '#/components/schemas/InboxWebhookAccount' }
-        timestamp: { type: string, format: date-time }
+        timestamp:
+          type: string
+          format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadCallFailed:
       type: object
       description: |
@@ -4093,7 +4260,10 @@ components:
                 code: { type: integer }
                 message: { type: string }
         account: { $ref: '#/components/schemas/InboxWebhookAccount' }
-        timestamp: { type: string, format: date-time }
+        timestamp:
+          type: string
+          format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadCallPermissionRequest:
       type: object
       description: |
@@ -4115,7 +4285,10 @@ components:
             expirationTimestamp: { type: string, format: date-time, description: "Present only when temporary" }
             responseSource: { type: string, description: "Meta's response source, typically `user_action`" }
         account: { $ref: '#/components/schemas/InboxWebhookAccount' }
-        timestamp: { type: string, format: date-time }
+        timestamp:
+          type: string
+          format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadAdStatusChanged:
       type: object
       description: |
@@ -4224,7 +4397,7 @@ components:
         timestamp:
           type: string
           format: date-time
-          description: ISO-8601 timestamp the webhook was produced.
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadWhatsAppTemplateStatusUpdated:
       type: object
       description: |
@@ -4277,7 +4450,70 @@ components:
         timestamp:
           type: string
           format: date-time
-          description: ISO-8601 timestamp the webhook was produced.
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
+    WebhookPayloadWhatsAppTemplateCategoryUpdated:
+      type: object
+      description: |
+        Webhook payload for the `whatsapp.template.category_updated` event.
+        Fired when Meta reclassifies a template's category attached to a
+        connected WABA. Maps Meta's `template_category_update` field onto
+        our event envelope.
+      required: [id, event, account, template, timestamp]
+      properties:
+        id:
+          type: string
+          description: Stable webhook event ID
+        event:
+          type: string
+          enum: [whatsapp.template.category_updated]
+        account:
+          type: object
+          required: [accountId, profileId, platform, username]
+          properties:
+            accountId: { type: string }
+            profileId: { type: string }
+            platform: { type: string, enum: [whatsapp] }
+            username: { type: string }
+            displayName: { type: string }
+        template:
+          type: object
+          required: [templateId, name, language, changeType, category]
+          properties:
+            templateId:
+              type: string
+              description: Meta's `message_template_id`, returned as a string.
+            name:
+              type: string
+              description: Meta's `message_template_name`.
+            language:
+              type: string
+              description: Meta's `message_template_language` (e.g. `en_US`).
+            changeType:
+              type: string
+              enum: [scheduled, applied]
+              description: |
+                `scheduled` is Meta's 24h advance notice of an upcoming
+                reclassification; `applied` is the change taking effect.
+            category:
+              type: string
+              enum: [UTILITY, MARKETING, AUTHENTICATION]
+              description: The category right now, regardless of changeType.
+            previousCategory:
+              type: string
+              enum: [UTILITY, MARKETING, AUTHENTICATION]
+              description: Present only when changeType is `applied`. The category before this change.
+            scheduledCategory:
+              type: string
+              enum: [UTILITY, MARKETING, AUTHENTICATION]
+              description: Present only when changeType is `scheduled`. The category that will take effect at `effectiveAt`.
+            effectiveAt:
+              type: string
+              format: date-time
+              description: Present only when changeType is `scheduled`. ISO-8601 timestamp when the scheduled category takes effect.
+        timestamp:
+          type: string
+          format: date-time
+          description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
     WebhookPayloadTest:
       type: object
       description: Webhook payload for test deliveries
@@ -4295,6 +4531,7 @@ components:
         timestamp:
           type: string
           format: date-time
+          description: 'UTC time at which Zernio generated this test event (set once when the payload is built). Test fires are sent synchronously as a single attempt; a later redelivery of this event keeps the original value.'
     DiscordGuildMember:
       type: object
       description: A Discord guild member, returned verbatim from Discord's API.
@@ -4387,18 +4624,34 @@ components:
       description: >
         A media item on a native (external/synced) post, as carried by post.external.*
         webhook payloads. Distinct from the richer MediaItem used for Zernio-authored
-        posts: external items are always already-published (url required) and limited to
-        image or video. Kept as a separate schema so the generated SDK model does not
-        collide with MediaItem.
+        posts: external items are always already-published and limited to image or
+        video. Kept as a separate schema so the generated SDK model does not collide
+        with MediaItem.
       required: [type, url]
       properties:
         type:
           type: string
           enum: [image, video]
         url:
-          type: string
+          type: [string, "null"]
+          description: >-
+            'Direct URL to the media file. Null when the platform withholds it: check
+            mediaStatus before downloading. Instagram omits the video file for Reels it
+            flags as containing copyrighted material (its docs name audio as the usual
+            cause), so type stays "video" while the file is permanently unreachable.
+            For LinkedIn videos where the platform returns no file, url falls back to
+            the cover image and the item carries mediaStatus: unavailable.'
         thumbnail:
           type: string
+          description: 'Cover image. Still present when url is null.'
+        mediaStatus:
+          type: string
+          enum: [available, unavailable]
+          description: 'unavailable means the media file could not be retrieved (url is null or, for LinkedIn videos, a cover image standing in for the file). available or absent means the file is available at url (older synced items omit the field).'
+        unavailableReason:
+          type: string
+          enum: [platform_withheld]
+          description: 'Why the file is missing. platform_withheld means the platform declined to return it and retrying will not help.'
     PlatformTarget:
       type: object
       properties:
@@ -4449,9 +4702,8 @@ components:
           description: The native post ID on the platform (populated after successful publish)
           example: "1234567890123456789"
         platformPostUrl:
-          type: string
-          format: uri
-          description: Public URL of the published post. Included in the response for immediate posts; for scheduled posts, fetch via GET /v1/posts/{postId} after publish time.
+          type: [string, "null"]
+          description: Public URL of the published post. Included in the response for immediate posts; for scheduled posts, fetch via GET /v1/posts/{postId} after publish time. Empty when the platform confirmed the publish without returning an id a permalink can be built from (TikTok returns a publish id for some uploads); the TikTok reconcile cron backfills it later.
           example: "https://twitter.com/acmecorp/status/1234567890123456789"
         publishedAt:
           type: string
@@ -4488,8 +4740,8 @@ components:
           description: Human-readable error message when status is failed. Contains platform-specific error details explaining why the publish failed.
         errorCategory:
           type: string
-          enum: [auth_expired, user_content, user_abuse, account_issue, platform_rejected, platform_error, system_error, unknown]
-          description: "Error category for programmatic handling: auth_expired (token expired/revoked), user_content (wrong format/too long), user_abuse (rate limits/spam), account_issue (config problems), platform_rejected (policy violation), platform_error (5xx/maintenance), system_error (Zernio infra), unknown"
+          enum: [auth_expired, user_content, user_abuse, account_issue, platform_rejected, platform_error, platform_rate_limit, quota_exhausted, system_error, unknown]
+          description: "Error category for programmatic handling: auth_expired (token expired/revoked), user_content (wrong format/too long), user_abuse (rate limits/spam), account_issue (config problems), platform_rejected (policy violation), platform_error (5xx/maintenance), platform_rate_limit (platform throttling, retried automatically), quota_exhausted (shared daily API quota empty, resumes at the platform's reset), system_error (Zernio infra), unknown"
         errorSource:
           type: string
           enum: [user, platform, system]
@@ -4631,9 +4883,239 @@ components:
           format: date-time
           description: When the last recycled copy was created (read-only)
 
+    XArticleTextRange:
+      type: object
+      additionalProperties: false
+      required: [from_index, to_index, text]
+      properties:
+        from_index:
+          type: integer
+          minimum: 0
+          description: Inclusive start index in the block text.
+        to_index:
+          type: integer
+          minimum: 0
+          description: Exclusive end index in the block text. Must be greater than or equal to from_index and no greater than the block text length.
+        text: { type: string, description: Text represented by this metadata range. }
+
+    XArticleInlineStyleRange:
+      type: object
+      additionalProperties: false
+      required: [offset, length, style]
+      properties:
+        offset: { type: integer, minimum: 0 }
+        length: { type: integer, minimum: 0 }
+        style: { type: string, enum: [bold, italic, strikethrough] }
+      description: The offset plus length must not exceed the containing block's text length.
+
+    XArticleEntityRange:
+      type: object
+      additionalProperties: false
+      required: [key, offset, length]
+      properties:
+        key:
+          type: integer
+          minimum: 0
+          description: Zero-based index into content_state.entities.
+        offset: { type: integer, minimum: 0 }
+        length: { type: integer, minimum: 0 }
+      description: The referenced entity must exist, and offset plus length must not exceed the containing block's text length.
+
+    XArticleBlock:
+      type: object
+      additionalProperties: false
+      required: [type, text]
+      properties:
+        type:
+          type: string
+          enum: [unstyled, header-one, header-two, header-three, unordered-list-item, ordered-list-item, blockquote, atomic]
+        text: { type: string }
+        key: { type: string, minLength: 1 }
+        data:
+          type: object
+          additionalProperties: false
+          properties:
+            cashtags: { type: array, items: { $ref: '#/components/schemas/XArticleTextRange' } }
+            hashtags: { type: array, items: { $ref: '#/components/schemas/XArticleTextRange' } }
+            mentions: { type: array, items: { $ref: '#/components/schemas/XArticleTextRange' } }
+            urls: { type: array, items: { $ref: '#/components/schemas/XArticleTextRange' } }
+        inline_style_ranges:
+          type: array
+          items: { $ref: '#/components/schemas/XArticleInlineStyleRange' }
+        entity_ranges:
+          type: array
+          items: { $ref: '#/components/schemas/XArticleEntityRange' }
+
+    XArticleEntity:
+      oneOf:
+        - type: object
+          additionalProperties: false
+          required: [key, value]
+          properties:
+            key: { type: string, minLength: 1 }
+            value:
+              type: object
+              additionalProperties: false
+              required: [type, mutability, data]
+              properties:
+                type: { type: string, const: post }
+                mutability: { type: string, enum: [immutable, mutable, segmented] }
+                data:
+                  type: object
+                  additionalProperties: false
+                  required: [post_id]
+                  properties:
+                    post_id: { type: string, minLength: 1 }
+        - type: object
+          additionalProperties: false
+          required: [key, value]
+          properties:
+            key: { type: string, minLength: 1 }
+            value:
+              type: object
+              additionalProperties: false
+              required: [type, mutability, data]
+              properties:
+                type: { type: string, const: link }
+                mutability: { type: string, enum: [immutable, mutable, segmented] }
+                data:
+                  type: object
+                  additionalProperties: false
+                  required: [url]
+                  properties:
+                    url: { type: string, format: uri }
+        - type: object
+          additionalProperties: false
+          required: [key, value]
+          properties:
+            key: { type: string, minLength: 1 }
+            value:
+              type: object
+              additionalProperties: false
+              required: [type, mutability, data]
+              properties:
+                type: { type: string, const: image }
+                mutability: { type: string, enum: [immutable, mutable, segmented] }
+                data:
+                  type: object
+                  additionalProperties: false
+                  required: [url]
+                  properties:
+                    url:
+                      type: string
+                      format: uri
+                      pattern: '^https?://.+\.(?:[jJ][pP][eE]?[gG]|[pP][nN][gG]|[wW][eE][bB][pP]|[gG][iI][fF]|[mM][pP]4)(?:[?#].*)?$'
+                      description: Public image, GIF, or MP4 URL. Zernio uploads it to X and replaces it with native media metadata. Caller-supplied media IDs are rejected.
+                    caption: { type: string }
+                    altText:
+                      type: string
+                      maxLength: 1000
+                      description: Supported for image and GIF URLs; rejected for MP4 media.
+        - type: object
+          additionalProperties: false
+          required: [key, value]
+          properties:
+            key: { type: string, minLength: 1 }
+            value:
+              type: object
+              additionalProperties: false
+              required: [type, mutability, data]
+              properties:
+                type: { type: string, const: emoji }
+                mutability: { type: string, enum: [immutable, mutable, segmented] }
+                data:
+                  type: object
+                  additionalProperties: false
+                  required: [entity_key]
+                  properties:
+                    entity_key: { type: string, minLength: 1 }
+        - type: object
+          additionalProperties: false
+          required: [key, value]
+          properties:
+            key: { type: string, minLength: 1 }
+            value:
+              type: object
+              additionalProperties: false
+              required: [type, mutability, data]
+              properties:
+                type: { type: string, const: markdown }
+                mutability: { type: string, enum: [immutable, mutable, segmented] }
+                data:
+                  type: object
+                  additionalProperties: false
+                  required: [markdown]
+                  properties:
+                    markdown: { type: string }
+        - type: object
+          additionalProperties: false
+          required: [key, value]
+          properties:
+            key: { type: string, minLength: 1 }
+            value:
+              type: object
+              additionalProperties: false
+              required: [type, mutability, data]
+              properties:
+                type: { type: string, enum: [divider, latex] }
+                mutability: { type: string, enum: [immutable, mutable, segmented] }
+                data: { type: object, additionalProperties: false }
+      description: Entity keys must be unique decimal strings matching their zero-based array index (`"0"`, `"1"`, ...).
+
+    XArticleContentState:
+      type: object
+      additionalProperties: false
+      externalDocs:
+        description: Official X Article content format reference
+        url: https://docs.x.com/x-api/articles/create-draft-article
+      required: [blocks, entities]
+      properties:
+        blocks:
+          type: array
+          minItems: 1
+          items: { $ref: '#/components/schemas/XArticleBlock' }
+        entities:
+          type: array
+          items: { $ref: '#/components/schemas/XArticleEntity' }
+      description: X's snake_case content-state shape. Standard DraftJS camelCase fields such as entityMap, inlineStyleRanges, and entityRanges are rejected.
+
+    XArticle:
+      type: object
+      additionalProperties: false
+      required: [title, content_state]
+      properties:
+        title: { type: string, minLength: 1 }
+        content_state: { $ref: '#/components/schemas/XArticleContentState' }
+        mode:
+          type: string
+          enum: [publish, draft]
+          default: publish
+          description: Publish creates an X Article draft and then publishes it. Draft stops after draft creation and returns the X draft ID without a public URL.
+        cover:
+          type: object
+          additionalProperties: false
+          required: [url]
+          properties:
+            url:
+              type: string
+              format: uri
+              pattern: '^https?://.+\.(?:[jJ][pP][eE]?[gG]|[pP][nN][gG]|[wW][eE][bB][pP])(?:[?#].*)?$'
+              description: Public JPG, JPEG, PNG, or WebP URL. GIF, MP4, AVIF, extensionless URLs, and caller-supplied native media IDs are rejected.
+            altText: { type: string, maxLength: 1000 }
+      description: |
+        Long-form X Article payload. X Articles require an eligible X Premium+ account.
+        Articles are mutually exclusive with top-level/custom tweet media and with threadItems,
+        poll, quoteTweetId, replyToTweetId, inReplyToTweetId, replySettings, sensitiveMedia,
+        paidPartnership, and madeWithAi. Publishing normally performs two billable X API
+        requests at $0.010 each (draft + publish, $0.020 total); mode `draft` performs only
+        the $0.010 draft request. `articleDraftId` is an internal recovery checkpoint and
+        must not be supplied by API clients.
+
     TwitterPlatformData:
       type: object
       properties:
+        article:
+          $ref: '#/components/schemas/XArticle'
         replyToTweetId:
           type: string
           description: ID of an existing tweet to reply to. The published tweet will appear as a reply in that tweet's thread. For threads, only the first tweet replies to the target; subsequent tweets chain normally. X only permits replying to your own posts or posts you are mentioned in; replying to an arbitrary other account's post is rejected by X.
@@ -4707,9 +5189,9 @@ components:
               type: boolean
               description: Content has other sensitive characteristics.
       description: >
-        X (Twitter) geo-restriction applies at the media level. Media in geo-restricted tweets will be
-        hidden for users outside the specified countries; the tweet text itself remains visible globally.
-        Requires media to be attached (ignored for text-only tweets).
+        X-specific post options. The article field creates a long-form X Article and is mutually
+        exclusive with tweet media and tweet-only options. Geo-restriction applies at the media
+        level: media is hidden outside the specified countries while tweet text remains visible.
 
     ThreadsPlatformData:
       type: object
@@ -4775,7 +5257,7 @@ components:
         carouselCards:
           type: array
           minItems: 2
-          maxItems: 5
+          maxItems: 10
           description: >
             Renders the post as a multi-link carousel (organic Page post). When set, mediaItems
             must be provided with the same length and all items must be images (no videos).
@@ -4955,13 +5437,41 @@ components:
           description: Set to true to disable automatic link previews for URLs in the post content (default is false)
         reshareUrl:
           type: string
-          description: "LinkedIn post link to repost (use the post's \"Copy link to post\" action), or a urn:li:share / urn:li:ugcPost / urn:li:groupPost URN. The published post becomes a quote-reshare: your content is shown as the commentary and the original post is embedded underneath (LinkedIn's \"repost with your thoughts\"). Mutually exclusive with media. Works on personal profiles and organization pages."
+          description: "LinkedIn post link to repost (use the post's \"Copy link to post\" action), or a urn:li:share / urn:li:ugcPost / urn:li:groupPost URN. With content, the published post is a quote-reshare: your text is the commentary and the original is embedded underneath (LinkedIn's \"repost with your thoughts\"). Leave content empty (and omit customContent) to publish a plain repost with no text, LinkedIn's one-click \"Repost\". Mutually exclusive with media. Works on personal profiles and organization pages."
         geoRestriction:
           $ref: '#/components/schemas/GeoRestriction'
+        poll:
+          type: object
+          description: 'Create a LinkedIn poll with this post. Cannot be combined with media or reshareUrl. Polls cannot be edited after publishing on LinkedIn, and API-created polls are non-sponsored only (they cannot be promoted as ads).'
+          properties:
+            question:
+              type: string
+              minLength: 1
+              maxLength: 140
+              description: 'Poll question (max 140 characters)'
+            options:
+              type: array
+              minItems: 2
+              maxItems: 4
+              items:
+                type: string
+                minLength: 1
+                maxLength: 30
+              description: 'Poll options (2-4 choices, max 30 characters each)'
+            duration:
+              type: string
+              enum: [ONE_DAY, THREE_DAYS, SEVEN_DAYS, FOURTEEN_DAYS]
+              default: SEVEN_DAYS
+              description: How long the poll accepts votes. Defaults to SEVEN_DAYS.
+          required:
+            - question
+            - options
       description: >
         Up to 20 images, no multi-video. Single PDF supported (max 100MB). Link previews auto-generated
         when no media attached. Use organizationUrn for multi-org posting. Geo-restriction only works for
         organization pages (not personal profiles) and requires the targeted audience to exceed 300 followers.
+        Polls are supported via the poll object: 2-4 options, cannot be combined with media or reshareUrl,
+        cannot be edited after publishing, and API-created polls are non-sponsored only.
 
     MoneyAmount:
       type: object
@@ -5649,6 +6159,21 @@ components:
     BlueskyPlatformData:
       type: object
       properties:
+        langs:
+          type: array
+          minItems: 1
+          maxItems: 3
+          items:
+            type: string
+          example: ["pt", "en"]
+          description: >
+            Language(s) of the post text as 1-3 BCP-47 codes (e.g. "pt", "en-US"), written to the
+            post record's langs field. Bluesky feed generators filter on this field, so posts
+            without it never appear in language-scoped feeds. Can only be set at creation
+            (Bluesky has no post editing). When threadItems is used, every item in the thread
+            carries the same langs. When omitted, the account's default (set via
+            PATCH /v1/accounts/{accountId}/bluesky-settings) applies; with no default either,
+            the field is absent from the record.
         threadItems:
           type: array
           description: >
@@ -5666,7 +6191,7 @@ components:
                 items:
                   $ref: '#/components/schemas/MediaItem'
       description: |
-        Bluesky post settings. Supports text posts with up to 4 images or a single video. threadItems creates a reply chain (Bluesky thread). Images exceeding 1MB are automatically compressed. Alt text supported via mediaItem properties.
+        Bluesky post settings. Supports text posts with up to 4 images or a single video. threadItems creates a reply chain (Bluesky thread). Images exceeding 1MB are automatically compressed. Alt text supported via mediaItem properties. Use langs to tag post language for feed-generator filtering.
 
     DiscordPlatformData:
       type: object
@@ -5916,7 +6441,7 @@ components:
         _id: { type: string }
         platform:
           type: string
-          enum: [tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, discord, slack, whatsapp, linkedinads, metaads, pinterestads, tiktokads, xads, googleads, openaiads]
+          enum: [tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, discord, slack, whatsapp, linkedinads, metaads, pinterestads, tiktokads, xads, googleads, openaiads, sms, phone, rcs]
         profileId:
           oneOf:
             - type: string
@@ -6083,12 +6608,18 @@ components:
       properties:
         billingSystem:
           type: string
-          enum: [metronome, stripe]
+          enum: [metronome, stripe, shopify]
         plan:
           type: object
           properties:
             name: { type: string }
             isUsageBased: { type: boolean }
+            isPaid:
+              type: boolean
+              description: 'True when the key belongs to an account with an active paid billing relationship (Stripe subscription, Metronome enrollment, or Shopify-managed billing).'
+        shopifyShopDomain:
+          type: [string, "null"]
+          description: 'myshopify.com domain owning the subscription; present only when billingSystem is shopify.'
         period:
           type: object
           description: Current billing cycle. `start`/`end` are resolved for usage-based accounts only.
@@ -6418,14 +6949,14 @@ components:
         likes: { type: integer, example: 0 }
         comments: { type: integer, example: 0 }
         shares: { type: integer, example: 0 }
-        saves: { type: integer, example: 0, description: 'Number of saves/bookmarks (Instagram, Pinterest)' }
+        saves: { type: integer, example: 0, description: 'Number of saves/bookmarks (Instagram, Pinterest, X/Twitter)' }
         clicks: { type: integer, example: 0 }
         views: { type: integer, example: 0 }
         follows: { type: integer, example: 0, description: 'Instagram feed posts and stories only: organic accounts that started following from this post. 0 for reels and other platforms.' }
         igReelsAvgWatchTime: { type: integer, example: 0, description: 'Instagram Reels only: average watch time per play, in milliseconds. 0 for non-Reels media and other platforms.' }
         igReelsVideoViewTotalTime: { type: integer, example: 0, description: 'Instagram Reels only: total watch time including replays, in milliseconds. 0 for non-Reels media and other platforms.' }
         videoDurationSeconds: { type: [integer, "null"], example: 30, description: 'Video length in seconds. Currently Instagram Reels only; combine with igReelsAvgWatchTime (ms) to estimate retention. Null when unknown (other platforms, non-video media, or when Instagram does not expose the media URL, e.g. reels with copyrighted audio).' }
-        engagementRate: { type: number, example: 0 }
+        engagementRate: { type: number, example: 6.59, description: 'Percentage, rounded to 2 decimals: (likes + comments + shares + saves) / (impressions or reach or views) * 100. Clicks and follows are never counted. The denominator is the FIRST of impressions, reach, views that is non-zero, so it is not the same basis on every post: a post with impressions divides by impressions, one without falls back to reach, then to views. If you need a single consistent basis (e.g. interactions / reach), compute it from the raw fields above. The engagementRate on the LinkedIn account endpoints is a different formula.' }
         lastUpdated: { type: string, format: date-time }
     PlatformAnalytics:
       type: object
@@ -6483,11 +7014,26 @@ components:
             type: object
             properties:
               type: { type: string, enum: [image, video] }
-              url: { type: string, format: uri, description: Direct URL to the media }
-              thumbnail: { type: string, format: uri, description: Thumbnail URL (same as url for images) }
+              url:
+                type: [string, "null"]
+                format: uri
+                description: >-
+                  'Direct URL to the media file. Null when the platform withholds it: check
+                  mediaStatus before downloading. Instagram omits the video file for Reels it
+                  flags as containing copyrighted material (its docs name audio as the usual
+                  cause), so type stays "video" while the file is permanently unreachable.'
+              thumbnail: { type: [string, "null"], format: uri, description: 'Thumbnail URL (same as url for images). Still present when url is null.' }
               altText:
                 type: string
                 description: Accessibility alt text set on the media, when present.
+              mediaStatus:
+                type: string
+                enum: [available, unavailable]
+                description: 'unavailable means the media file could not be retrieved (url is null or, for LinkedIn videos, a cover image standing in for the file). available or absent means the file is available at url (older synced items omit the field).'
+              unavailableReason:
+                type: string
+                enum: [platform_withheld]
+                description: 'Why the file is missing. platform_withheld means the platform declined to return it and retrying will not help.'
     AnalyticsListResponse:
       type: object
       properties:
@@ -6563,7 +7109,7 @@ components:
             shares: { type: integer, description: Total reshares across all posts }
             saves: { type: integer, description: Total times posts were saved (personal accounts only) }
             sends: { type: integer, description: Total times posts were sent via LinkedIn messaging (personal accounts only) }
-            engagementRate: { type: number, description: Overall engagement rate as percentage }
+            engagementRate: { type: number, description: 'Overall engagement rate, as a percentage rounded to 2 decimals: (reactions + comments + shares + saves + sends) / impressions * 100. Clicks are not counted, and there is no fallback denominator, so this is 0 whenever impressions is 0. This is NOT the same formula as PostAnalytics.engagementRate on GET /v1/analytics.' }
         note: { type: string }
         lastUpdated: { type: string, format: date-time }
     LinkedInAggregateAnalyticsDailyResponse:
@@ -7011,7 +7557,7 @@ components:
           type: object
           additionalProperties:
             type: integer
-          description: "Per-action-type counts summed over the date range, keyed by the platform's action-type names. Meta: raw Insights action_type keys (link_click, offsite_conversion.fb_pixel_purchase, onsite_conversion.lead_grouped, ...) — both engagement and conversion events. X: conversion types (purchase, sign_up, site_visit, download, custom). LinkedIn: conversion types (post_click, post_view, lead_gen). Google returns {} (its per-action names aren't synced per ad). Empty object when no actions are reported. NOTE: keys differ by platform, so branch on the ad's platform when interpreting them."
+          description: "Per-action-type counts summed over the date range, keyed by the platform's action-type names. Meta: raw Insights action_type keys (link_click, offsite_conversion.fb_pixel_purchase, onsite_conversion.lead_grouped, ...) — both engagement and conversion events. TikTok: pixel conversions (purchase, add_to_cart, initiate_checkout, view_content, complete_payment, lead) plus the paid-engagement family (follow, post_reaction for paid likes, comment, share) — follow is how FOLLOWERS-goal campaigns report their result. X: conversion types (purchase, sign_up, site_visit, download, custom). LinkedIn: conversion types (post_click, post_view, lead_gen). Google returns {} (its per-action names aren't synced per ad). Empty object when no actions are reported. NOTE: keys differ by platform, so branch on the ad's platform when interpreting them."
           example:
             link_click: 160
             post_engagement: 300
@@ -7108,13 +7654,17 @@ components:
         Use these fields when you need a specific interaction, and `engagement`
         only as the coarse total it has always been.
 
-        Meta-only; other platforms leave these at 0.
+        Populated for Meta and, since 2026-08, TikTok (`reactions` = paid
+        likes, `comments`, `shares`; TikTok's `follow` count lives in
+        `actions.follow`, not here). Other platforms leave these at 0.
+        TikTok history note: paused TikTok ads are not re-synced, so
+        campaigns that ended before the rollout keep 0s here.
       properties:
-        postEngagement: { type: integer, description: "Meta's own post-engagement total (`post_engagement`)." }
-        pageEngagement: { type: integer, description: "Meta's own page-engagement total (`page_engagement`)." }
-        reactions: { type: integer, description: "Reactions on the ad's post (`post_reaction`)." }
+        postEngagement: { type: integer, description: "Meta's own post-engagement total (`post_engagement`). Meta-only." }
+        pageEngagement: { type: integer, description: "Meta's own page-engagement total (`page_engagement`). Meta-only." }
+        reactions: { type: integer, description: "Reactions on the ad's post (`post_reaction`). For TikTok these are its paid likes." }
         comments: { type: integer, description: "Comments on the ad's post." }
-        shares: { type: integer, description: "Shares of the ad's post. Meta reports these under the action type literally named `post`." }
+        shares: { type: integer, description: "Shares of the ad's post. Meta reports these under the action type literally named `post`; TikTok under `share`." }
         saves: { type: integer, description: "Saves of the ad's post (`onsite_conversion.post_save`)." }
         pageLikes: { type: integer, description: "New Page likes attributed to the ad (`like`)." }
         videoViews: { type: integer, description: "3-second video views (`video_view`). For completion-based counts use `videoThruplayWatchedActions`." }
@@ -7605,6 +8155,7 @@ components:
             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." }
             videoUrl: { type: [string, "null"], description: "Public Facebook watch URL for VIDEO-type ads (https://www.facebook.com/watch/?v={videoId}). Null for non-video ads." }
+            creativeId: { type: [string, "null"], description: "Meta ad creative id backing this ad. Reusable via existingCreativeId on POST /v1/ads/create." }
             objectType: { type: string, description: "Meta creative object_type (e.g. SHARE, VIDEO, PRIVACY_CHECK_FAIL, POST_DELETED). Use this to render state-aware previews — when Meta moderation strips image/video fields, only thumbnailUrl at 64x64 is available." }
             objectStoryId: { type: [string, "null"], description: "Meta creative `object_story_id` (the SHARE reference). Frequently absent — Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead." }
             effectiveObjectStoryId: { type: [string, "null"], description: "Meta `effective_object_story_id` — `{pageId}_{postId}` of the Facebook post the ad's engagement (comments) lives on. Pass to GET /v1/ads?effectiveObjectStoryId= to map a Business-Manager-visible post back to this ad; GET /v1/ads/{adId}/comments resolves comments against it." }
@@ -7762,7 +8313,7 @@ components:
         profileId: { type: string }
         advertisingChannelType:
           type: [string, "null"]
-          description: "Google-only. Raw campaign.advertising_channel_type (SEARCH, PERFORMANCE_MAX, VIDEO, DEMAND_GEN, DISPLAY, SHOPPING, ...). Serving surface, distinct from platformObjective (advertiser intent). Null/absent for non-Google platforms."
+          description: "Google-only. Raw campaign.advertising_channel_type (SEARCH, PERFORMANCE_MAX, LOCAL_SERVICES, VIDEO, DEMAND_GEN, DISPLAY, SHOPPING, ...). Serving surface, distinct from platformObjective (advertiser intent). Null/absent for non-Google platforms."
         platformObjective: { type: [string, "null"], description: "Raw Meta campaign objective (e.g. OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC)" }
         optimizationGoal:
           type: [string, "null"]
@@ -8065,6 +8616,37 @@ components:
         customConversionId: { type: string, description: "Drops straight into promotedObject.customConversionId on POST /v1/ads/create." }
         reused: { type: boolean, description: "True when an existing conversion matched name + pixelId; the response is then a 200." }
         customConversion: { $ref: '#/components/schemas/CustomConversion' }
+    Blog:
+      type: object
+      description: 'A blog container on the connected platform. All content lives on the platform; Zernio proxies it and stores nothing.'
+      properties:
+        id: { type: string, description: 'Platform-native blog id (numeric string for Shopify).' }
+        platform: { type: string, enum: [shopify] }
+        title: { type: string }
+        handle: { type: string, description: 'URL slug of the blog.' }
+    BlogArticle:
+      type: object
+      description: 'An article inside a blog on the connected platform.'
+      properties:
+        id: { type: string, description: 'Platform-native article id (numeric string for Shopify).' }
+        blogId: { type: string, description: 'Platform-native id of the blog the article belongs to.' }
+        platform: { type: string, enum: [shopify] }
+        title: { type: string }
+        bodyHtml: { type: [string, "null"], description: 'Article body as HTML.' }
+        handle: { type: string, description: 'URL slug of the article.' }
+        tags: { type: array, items: { type: string } }
+        author: { type: [string, "null"], description: 'Display name of the article author.' }
+        excerpt: { type: [string, "null"], description: 'Short summary shown in blog listings.' }
+        image:
+          type: [object, "null"]
+          description: Featured image.
+          properties:
+            url: { type: string }
+            altText: { type: [string, "null"] }
+        isPublished: { type: boolean, description: 'False while the article is a draft or its publish date is still in the future.' }
+        publishedAt: { type: [string, "null"], format: date-time, description: 'When the article was (or is scheduled to be) published; null for drafts.' }
+        createdAt: { type: [string, "null"], format: date-time }
+        updatedAt: { type: [string, "null"], format: date-time }
     TrackingTag:
       type: object
       description: |
@@ -8594,6 +9176,31 @@ webhooks:
       responses:
         '200':
           description: Webhook received successfully
+  referral.received:
+    post:
+      operationId: onReferralReceived
+      summary: Referral received event
+      description: |
+        Fired when someone opens an EXISTING Instagram or Messenger thread
+        through an attributable entry point - an ig.me / m.me link with a
+        `ref` parameter, or (Messenger) a returning Click-to-Message ad click -
+        which Meta delivers as a standalone referral with no message attached.
+        A referral that rides an inbound message (first message of a thread,
+        icebreaker taps, returning ad clicks on Instagram) arrives on
+        `message.received` under `metadata.referral` instead; the two never
+        fire for the same click. The first referral captured on a conversation
+        is also persisted on it (see `metadata` on `GET
+        /v1/inbox/conversations`). Requires the Inbox add-on.
+      tags: [Webhook Events]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WebhookPayloadReferral'
+      responses:
+        '200':
+          description: Webhook received successfully
   comment.received:
     post:
       operationId: onCommentReceived
@@ -8839,6 +9446,28 @@ webhooks:
       responses:
         '200':
           description: Webhook received successfully
+  whatsapp.template.category_updated:
+    post:
+      operationId: onWhatsAppTemplateCategoryUpdated
+      summary: WhatsApp template category updated event
+      description: |
+        Fired when Meta reclassifies a WhatsApp Business template's category
+        after approval. Forwarded from Meta's `template_category_update`
+        webhook field on the WhatsApp Business Account. Category drives
+        Meta's per-conversation tariff and whether the template is subject
+        to the recipient's marketing opt-out. `template.changeType` is
+        `scheduled` (24h advance notice) or `applied`; `template.category`
+        is always the category right now.
+      tags: [Webhook Events]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WebhookPayloadWhatsAppTemplateCategoryUpdated'
+      responses:
+        '200':
+          description: Webhook received successfully
   whatsapp.automatic_event:
     post:
       operationId: onWhatsAppAutomaticEvent
@@ -8862,7 +9491,10 @@ webhooks:
               properties:
                 id: { type: string }
                 event: { type: string, enum: [whatsapp.automatic_event] }
-                timestamp: { type: string, format: date-time }
+                timestamp:
+                  type: string
+                  format: date-time
+                  description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
                 accountId:
                   type: string
                   description: SocialAccount id of the WhatsApp number whose conversation was flagged.
@@ -8907,7 +9539,10 @@ webhooks:
               properties:
                 id: { type: string }
                 event: { type: string, enum: [whatsapp.number.activated] }
-                timestamp: { type: string, format: date-time }
+                timestamp:
+                  type: string
+                  format: date-time
+                  description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
                 number:
                   type: object
                   properties:
@@ -8936,7 +9571,10 @@ webhooks:
               properties:
                 id: { type: string }
                 event: { type: string, enum: [whatsapp.number.declined] }
-                timestamp: { type: string, format: date-time }
+                timestamp:
+                  type: string
+                  format: date-time
+                  description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
                 number:
                   type: object
                   properties:
@@ -8968,7 +9606,10 @@ webhooks:
               properties:
                 id: { type: string }
                 event: { type: string, enum: [whatsapp.number.action_required] }
-                timestamp: { type: string, format: date-time }
+                timestamp:
+                  type: string
+                  format: date-time
+                  description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
                 reason: { type: string }
                 number:
                   type: object
@@ -8998,7 +9639,10 @@ webhooks:
               properties:
                 id: { type: string }
                 event: { type: string, enum: [whatsapp.number.verification_required] }
-                timestamp: { type: string, format: date-time }
+                timestamp:
+                  type: string
+                  format: date-time
+                  description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
                 number:
                   type: object
                   properties:
@@ -9029,7 +9673,10 @@ webhooks:
               properties:
                 id: { type: string }
                 event: { type: string, enum: [whatsapp.number.suspended] }
-                timestamp: { type: string, format: date-time }
+                timestamp:
+                  type: string
+                  format: date-time
+                  description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
                 number:
                   type: object
                   properties:
@@ -9058,7 +9705,10 @@ webhooks:
               properties:
                 id: { type: string }
                 event: { type: string, enum: [whatsapp.number.reactivated] }
-                timestamp: { type: string, format: date-time }
+                timestamp:
+                  type: string
+                  format: date-time
+                  description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
                 number:
                   type: object
                   properties:
@@ -9087,7 +9737,10 @@ webhooks:
               properties:
                 id: { type: string }
                 event: { type: string, enum: [whatsapp.number.released] }
-                timestamp: { type: string, format: date-time }
+                timestamp:
+                  type: string
+                  format: date-time
+                  description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
                 number:
                   type: object
                   properties:
@@ -9118,7 +9771,10 @@ webhooks:
               properties:
                 id: { type: string }
                 event: { type: string, enum: [whatsapp.number.kyc_submitted, verification.approved, verification.failed] }
-                timestamp: { type: string, format: date-time }
+                timestamp:
+                  type: string
+                  format: date-time
+                  description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
                 number:
                   type: object
                   properties:
@@ -9146,7 +9802,10 @@ webhooks:
               properties:
                 id: { type: string }
                 event: { type: string, enum: [verification.approved] }
-                timestamp: { type: string, format: date-time }
+                timestamp:
+                  type: string
+                  format: date-time
+                  description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
                 verification:
                   type: object
                   properties:
@@ -9173,7 +9832,10 @@ webhooks:
               properties:
                 id: { type: string }
                 event: { type: string, enum: [verification.failed] }
-                timestamp: { type: string, format: date-time }
+                timestamp:
+                  type: string
+                  format: date-time
+                  description: 'UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.'
                 verification:
                   type: object
                   properties:
@@ -12821,7 +13483,7 @@ paths:
                 lastVerified: "2026-03-26"
                 tiers:
                   - { tier: x_api_005, pricePerCallUsd: 0.005, operationCount: 13 }
-                  - { tier: x_api_010, pricePerCallUsd: 0.010, operationCount: 8 }
+                  - { tier: x_api_010, pricePerCallUsd: 0.010, operationCount: 10 }
                   - { tier: x_api_015, pricePerCallUsd: 0.015, operationCount: 3 }
                   - { tier: x_api_200, pricePerCallUsd: 0.200, operationCount: 1 }
                 operations:
@@ -12851,6 +13513,22 @@ paths:
                     tier: x_api_200
                     triggeredBy:
                       - { method: publishPost, metering: always }
+                  - operation: article_draft
+                    eventType: x_article_draft
+                    displayName: "X API: Article Draft"
+                    pricePerCallUsd: 0.010
+                    pricePerCallCents: 1.0
+                    tier: x_api_010
+                    triggeredBy:
+                      - { method: createArticleDraft, metering: always }
+                  - operation: article_publish
+                    eventType: x_article_publish
+                    displayName: "X API: Article Publish"
+                    pricePerCallUsd: 0.010
+                    pricePerCallCents: 1.0
+                    tier: x_api_010
+                    triggeredBy:
+                      - { method: publishArticle, metering: always }
         '401': { $ref: '#/components/responses/Unauthorized' }
   /v1/usage:
     get:
@@ -13296,7 +13974,7 @@ paths:
       summary: Create post
       description: |
         Create and optionally publish a post. Immediate posts (`publishNow: true`) include `platformPostUrl` in the response.
-        Content is optional when media is attached or all platforms have `customContent`. See each platform's schema for media constraints.
+        Content is optional when media is attached, all platforms have `customContent`, every platform entry is an X Article (`platformSpecificData.article`), or every platform entry is a LinkedIn plain repost (`platformSpecificData.reshareUrl` with no text). See each platform's schema for media constraints.
 
         ## Idempotency
 
@@ -13330,7 +14008,7 @@ paths:
                 title: { type: string }
                 content:
                   type: string
-                  description: Post caption/text. Optional when media is attached or all platforms have customContent. Required for text-only posts.
+                  description: 'Post caption/text. Optional when media is attached, all platforms have customContent, every platform entry is an X Article (platformSpecificData.article), or every platform entry is a LinkedIn plain repost (platformSpecificData.reshareUrl with no text). Required for other text-only posts.'
                 mediaItems:
                   type: array
                   items: { $ref: '#/components/schemas/MediaItem' }
@@ -13408,6 +14086,69 @@ paths:
                     Only used when queuedFromProfile is also provided.
                     If omitted, uses the profile's default queue.
             examples:
+              twitterArticle:
+                summary: Publish a long-form X Article
+                description: |
+                  Creates an X Article draft and publishes it. This normally makes two
+                  billable X API calls at $0.010 each ($0.020 total). The account must
+                  be eligible for X Articles (X Premium+). Article media is supplied as
+                  public URLs; Zernio uploads it to X and builds the native media shape.
+                value:
+                  platforms:
+                    - platform: twitter
+                      accountId: "64e1f0a9e2b5af0012ab34cd"
+                      platformSpecificData:
+                        article:
+                          title: "Building a better publishing workflow"
+                          mode: publish
+                          cover:
+                            url: "https://cdn.example.com/article-cover.jpg"
+                          content_state:
+                            blocks:
+                              - type: header-one
+                                text: "A reliable publishing workflow"
+                              - type: unstyled
+                                text: "Long-form publishing should be observable. Read the implementation notes."
+                                inline_style_ranges:
+                                  - { offset: 0, length: 9, style: bold }
+                                entity_ranges:
+                                  - { key: 0, offset: 52, length: 20 }
+                              - type: atomic
+                                text: " "
+                                entity_ranges:
+                                  - { key: 1, offset: 0, length: 1 }
+                            entities:
+                              - key: "0"
+                                value:
+                                  type: link
+                                  mutability: mutable
+                                  data:
+                                    url: "https://example.com/implementation-notes"
+                              - key: "1"
+                                value:
+                                  type: image
+                                  mutability: immutable
+                                  data:
+                                    url: "https://cdn.example.com/workflow.png"
+                                    caption: "The publishing stages"
+                  publishNow: true
+              twitterArticleDraft:
+                summary: Save an X Article as a platform draft
+                description: Creates only the X Article draft ($0.010) and does not publish it publicly.
+                value:
+                  platforms:
+                    - platform: twitter
+                      accountId: "64e1f0a9e2b5af0012ab34cd"
+                      platformSpecificData:
+                        article:
+                          title: "Draft product update"
+                          mode: draft
+                          content_state:
+                            blocks:
+                              - type: unstyled
+                                text: "This Article is ready for final review."
+                            entities: []
+                  publishNow: true
               facebookDraft:
                 summary: Facebook draft post (visible in Publishing Tools)
                 value:
@@ -13421,7 +14162,7 @@ paths:
               facebookCarousel:
                 summary: Facebook multi-link carousel post
                 description: |
-                  Posts a 2-5 card carousel where each image has its own click-through link
+                  Posts a 2-10 card carousel where each image has its own click-through link
                   and optional headline. mediaItems and carouselCards must have the same
                   length, in the same order. Images only (no video cards).
                 value:
@@ -15270,7 +16011,15 @@ paths:
       operationId: getAccountHealth
       tags: [Accounts]
       summary: Check account health
-      description: Returns detailed health info for a specific account including token status, permissions, and recommendations.
+      description: |
+        Returns detailed health info for a specific account including token status, permissions, and recommendations.
+
+        For WhatsApp accounts the response also includes `platformConnection`, a live probe of the
+        Meta link behind the channel (the same read as `GET /v1/whatsapp/number-info`). The OAuth
+        token can be perfectly valid while Meta refuses to serve the phone-number object (for
+        example after a phone-side coexistence disconnect), so `tokenStatus` alone is not a
+        liveness signal for WhatsApp. When the Meta link is dead, `platformConnection.status` is
+        `disconnected` and the overall `status` is `error`.
       parameters:
         - name: accountId
           in: path
@@ -15338,6 +16087,28 @@ paths:
                     type: array
                     items: { type: string }
                     description: Actionable recommendations to fix issues
+                  platformConnection:
+                    type: object
+                    description: 'WhatsApp accounts only. Live probe of the Meta link behind the channel, performed at request time (the same read as GET /v1/whatsapp/number-info).'
+                    properties:
+                      status:
+                        type: string
+                        enum: [connected, disconnected, unknown]
+                        description: '`connected` = Meta served the channel object. `disconnected` = Meta refused to serve it (Graph error 100, subcode 33), which is how a phone-side coexistence disconnect surfaces. `unknown` = the live read failed for another reason (timeout, transient Meta error), not evidence either way.'
+                      checkedAt:
+                        type: string
+                        format: date-time
+                        description: When this live probe ran (always the current request; never cached)
+                      phoneStatus:
+                        type: [string, "null"]
+                        description: 'Meta''s own `status` field from the phone-number node (for example CONNECTED), when the object was readable'
+                      metaError:
+                        type: [object, "null"]
+                        description: Set only when status is `disconnected`
+                        properties:
+                          code: { type: integer, description: 'Meta Graph error code (100)' }
+                          subcode: { type: integer, description: 'Meta Graph error subcode (33)' }
+                          message: { type: string }
               example:
                 accountId: "abc123"
                 platform: "instagram"
@@ -15367,6 +16138,7 @@ paths:
                   missingRequired: []
                 issues: []
                 recommendations: []
+        '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
   /v1/accounts/{accountId}/follow-status/{userId}:
@@ -15925,6 +16697,17 @@ paths:
             `facebook_login`: the Facebook Login dialog, i.e. "Instagram API with Facebook Login". The user authorizes a Facebook Page that has a linked Instagram professional account, and every API call for that account then runs through the Page. Use this when the customer manages Instagram through a Page and expects the Facebook consent screen. Because the user has to pick which Page to connect, the callback continues at the account-selection step, `/v1/connect/instagram/select-account`.
 
             `facebook_login` supports `headless=true` like the other selection platforms: the callback redirects to your `redirect_url` with `profileId`, `tempToken`, `platform=instagram`, `step=select_account` and `connect_token`, which you pass into the select-account endpoints to finish. The default `instagram_login` has no selection step, so it connects the account directly.
+        - name: onboarding
+          in: query
+          schema: { type: string, enum: [api, business_app] }
+          description: |
+            WhatsApp only. Ignored for every other platform. Controls which screen Meta's Embedded Signup popup shows.
+
+            If omitted, the connection defaults to coexistence (same as `business_app` below), preserving existing behavior for numbers already on the WhatsApp Business app.
+
+            `api`: standard Embedded Signup, showing Meta's WABA/number picker. Use this to connect a phone number already on Cloud API elsewhere.
+
+            `business_app`: coexistence, i.e. 'Connect existing WhatsApp Business app' (a number shared between Cloud API and the consumer WhatsApp Business app).
       security:
         - bearerAuth: []
       responses:
@@ -16121,6 +16904,124 @@ paths:
         '404':
           description: "Profile or posting account not found"
 
+  /v1/connect/shopify:
+    get:
+      x-resource-group: "accounts"
+      operationId: getShopifyConnectUrl
+      tags: [Connect]
+      summary: Get Shopify OAuth connect URL
+      description: |
+        Initiate the Shopify OAuth flow for a store. Shopify is a connect-only
+        platform: the connected account does not publish social posts, it powers
+        the Blogs API (`/v1/accounts/{accountId}/blogs`). Returns an `authUrl`
+        to redirect the merchant to; after they approve the install, Shopify
+        redirects their browser to Zernio's callback, the account is created on
+        the profile (platform `shopify`), and the browser is redirected to
+        `redirect_url` (or the Zernio dashboard when omitted). Requested scopes
+        are `read_content` and `write_content` (content only; no customer or
+        order data). Connecting the same profile to a store again refreshes the
+        stored token in place.
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: profileId
+          in: query
+          required: true
+          schema: { type: string }
+          description: 'Your Zernio profile ID (get from /v1/profiles).'
+        - name: shop
+          in: query
+          required: true
+          schema: { type: string }
+          description: 'The myshopify.com store domain to connect, e.g. `your-store.myshopify.com` (the bare `your-store` prefix is accepted too).'
+        - name: redirect_url
+          in: query
+          schema: { type: string, format: uri }
+          description: 'Your custom redirect URL after connection completes. Accepts an http(s) URL, a custom app scheme for mobile deeplinks (e.g. myapp://callback), or a relative path. On failure an `error` query param is appended.'
+      responses:
+        '200':
+          description: OAuth authorization URL to redirect the merchant to
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  authUrl:
+                    type: string
+                    format: uri
+                    description: URL to redirect your user to for OAuth authorization
+                  state:
+                    type: string
+                    description: State parameter for security (handled automatically)
+        '400':
+          description: 'Invalid `profileId` format, `shop` is not a myshopify.com store domain, or `redirect_url` uses a script-executing scheme.'
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '402': { $ref: '#/components/responses/PaymentRequired' }
+        '403':
+          description: 'API key does not have access to this profile.'
+        '404':
+          description: 'Profile not found or access denied.'
+        '500':
+          description: 'Shopify API not configured (missing credentials).'
+
+  /v1/connect/shopify/token:
+    post:
+      x-resource-group: "accounts"
+      operationId: connectShopifyWithToken
+      tags: [Connect]
+      summary: Connect a Shopify store with a custom-app Admin token
+      description: |
+        Token-paste alternative to the OAuth flow: connect a store using the
+        Admin API access token of a custom app the merchant created in their
+        own Shopify admin (Settings → Apps and sales channels → Develop apps,
+        with the `read_content`/`write_content` scopes). Use this when the
+        one-click OAuth connect is unavailable or when your users prefer not
+        to install a third-party app on their store. The token is validated
+        against the store before anything is saved; custom-app tokens do not
+        expire. Connecting the same profile to a store again replaces the
+        stored token in place.
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [profileId, shop, accessToken]
+              properties:
+                profileId:
+                  type: string
+                  description: 'Your Zernio profile ID (get from /v1/profiles).'
+                shop:
+                  type: string
+                  description: 'The myshopify.com store domain, e.g. `your-store.myshopify.com` (the bare `your-store` prefix is accepted too).'
+                accessToken:
+                  type: string
+                  description: 'Admin API access token of the merchant-created custom app (starts with `shpat_`).'
+      responses:
+        '200':
+          description: Store connected as a platform account
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  account:
+                    type: object
+                    properties:
+                      _id: { type: string }
+                      platform: { type: string, enum: [shopify] }
+                      username: { type: string, description: 'The myshopify.com domain of the connected store.' }
+                      displayName: { type: string }
+                      profileId: { type: string }
+        '400':
+          description: 'Invalid `profileId` format, `shop` is not a myshopify.com store domain, or Shopify rejected the access token for that store.'
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '402': { $ref: '#/components/responses/PaymentRequired' }
+        '403':
+          description: 'API key does not have access to this profile.'
+
   /v1/connect/tiktok-ads:
     patch:
       x-resource-group: "accounts"
@@ -19547,7 +20448,7 @@ paths:
         '403':
           description: Profile limit exceeded for this plan
         '409':
-          description: 'The phone number is a Zernio-provisioned number pinned to a different profile. Connect it from that profile, or move it first with PATCH /v1/whatsapp/phone-numbers/{id}/profile.'
+          description: 'Conflict with an existing connection. Either the phone number is a Zernio-provisioned number pinned to a different profile (code WHATSAPP_NUMBER_PINNED_TO_PROFILE, connect it from that profile or move it first with PATCH /v1/whatsapp/phone-numbers/{id}/profile), or the number is already actively connected on another profile or workspace (code WHATSAPP_NUMBER_ALREADY_CONNECTED, disconnect it there first). A number can only be live on one profile.'
 
   /v1/connect/whatsapp/select-phone-number:
     get:
@@ -19704,7 +20605,7 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
         '409':
-          description: 'The phone number is a Zernio-provisioned number pinned to a different profile. Connect it from that profile, or move it first with PATCH /v1/whatsapp/phone-numbers/{id}/profile.'
+          description: 'Conflict with an existing connection. Either the phone number is a Zernio-provisioned number pinned to a different profile (code WHATSAPP_NUMBER_PINNED_TO_PROFILE, connect it from that profile or move it first with PATCH /v1/whatsapp/phone-numbers/{id}/profile), or the number is already actively connected on another profile or workspace (code WHATSAPP_NUMBER_ALREADY_CONNECTED, disconnect it there first). A number can only be live on one profile.'
         '500':
           description: Failed to bind phone number
           content:
@@ -20297,7 +21198,7 @@ paths:
                       sends: { type: integer, description: Times the post was sent via LinkedIn messaging (personal accounts only; 0 for organization accounts) }
                       clicks: { type: integer, description: Clicks on the post (organization accounts only) }
                       views: { type: integer, description: Video views (video posts only) }
-                      engagementRate: { type: number, description: Engagement rate as percentage }
+                      engagementRate: { type: number, description: 'Engagement rate, as a percentage rounded to 2 decimals: (likes + comments + shares + clicks + saves + sends) / impressions * 100. Unlike PostAnalytics.engagementRate on GET /v1/analytics, this one DOES count clicks and has no fallback denominator, so it is 0 whenever impressions is 0. For organization accounts the value is the rate LinkedIn returns, not one computed here.' }
                   lastUpdated: { type: string, format: date-time }
               example:
                 accountId: "64abc123def456"
@@ -21811,6 +22712,65 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { description: Account not found }
 
+  /v1/accounts/{accountId}/bluesky-settings:
+    get:
+      x-resource-group: "accounts"
+      operationId: getBlueskySettings
+      tags: [Accounts]
+      summary: Get Bluesky account settings
+      description: 'Returns the account''s default post languages (defaultLangs), applied at publish time whenever a post''s platformSpecificData.langs is absent. Null when no default is set.'
+      parameters:
+        - name: accountId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: Bluesky account settings
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  defaultLangs:
+                    type: [array, "null"]
+                    items: { type: string }
+                    example: ["pt"]
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { description: Account not found }
+    patch:
+      x-resource-group: "accounts"
+      operationId: updateBlueskySettings
+      tags: [Accounts]
+      summary: Update Bluesky account settings
+      description: 'Set or clear the account''s default post languages. 1-3 BCP-47 codes (e.g. "pt", "en-US"), the same validation as per-post langs; explicit null clears the default. Per-post platformSpecificData.langs always overrides this default. Applies to posts published after the change; already-published posts cannot be retagged (Bluesky has no post edit).'
+      parameters:
+        - name: accountId
+          in: path
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [defaultLangs]
+              properties:
+                defaultLangs:
+                  type: [array, "null"]
+                  minItems: 1
+                  maxItems: 3
+                  items: { type: string }
+                  example: ["pt"]
+      responses:
+        '200':
+          description: Updated settings
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { description: Account not found }
+
   /v1/accounts/{accountId}/discord-settings:
     get:
       x-resource-group: "accounts"
@@ -23336,7 +24296,7 @@ paths:
                   minItems: 1
                   items:
                     type: string
-                    enum: [post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, post.platform.published, post.platform.failed, post.platform.deleted, post.tiktok.url_resolved, post.external.created, post.external.updated, post.external.deleted, account.connected, account.disconnected, account.ads.initial_sync_completed, message.received, conversation.started, call.received, call.ended, call.failed, call.permission_request, message.sent, message.edited, message.deleted, message.delivered, message.read, message.failed, reaction.received, comment.received, review.new, review.updated, lead.received, ad.status_changed, whatsapp.template.status_updated, whatsapp.automatic_event, whatsapp.number.activated, whatsapp.number.declined, whatsapp.number.action_required, whatsapp.number.verification_required, whatsapp.number.suspended, whatsapp.number.reactivated, whatsapp.number.released, whatsapp.number.kyc_submitted, verification.approved, verification.failed]
+                    enum: [post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, post.platform.published, post.platform.failed, post.platform.deleted, post.tiktok.url_resolved, post.external.created, post.external.updated, post.external.deleted, account.connected, account.disconnected, account.ads.initial_sync_completed, message.received, conversation.started, call.received, call.ended, call.failed, call.permission_request, message.sent, message.edited, message.deleted, message.delivered, message.read, message.failed, reaction.received, referral.received, comment.received, review.new, review.updated, lead.received, ad.status_changed, whatsapp.template.status_updated, whatsapp.template.category_updated, whatsapp.automatic_event, whatsapp.number.activated, whatsapp.number.declined, whatsapp.number.action_required, whatsapp.number.verification_required, whatsapp.number.suspended, whatsapp.number.reactivated, whatsapp.number.released, whatsapp.number.kyc_submitted, verification.approved, verification.failed]
                   description: Events to subscribe to (at least one required)
                 isActive:
                   type: boolean
@@ -23455,7 +24415,7 @@ paths:
                   minItems: 1
                   items:
                     type: string
-                    enum: [post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, post.platform.published, post.platform.failed, post.platform.deleted, post.tiktok.url_resolved, post.external.created, post.external.updated, post.external.deleted, account.connected, account.disconnected, account.ads.initial_sync_completed, message.received, conversation.started, call.received, call.ended, call.failed, call.permission_request, message.sent, message.edited, message.deleted, message.delivered, message.read, message.failed, reaction.received, comment.received, review.new, review.updated, lead.received, ad.status_changed, whatsapp.template.status_updated, whatsapp.automatic_event, whatsapp.number.activated, whatsapp.number.declined, whatsapp.number.action_required, whatsapp.number.verification_required, whatsapp.number.suspended, whatsapp.number.reactivated, whatsapp.number.released, whatsapp.number.kyc_submitted, verification.approved, verification.failed]
+                    enum: [post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, post.platform.published, post.platform.failed, post.platform.deleted, post.tiktok.url_resolved, post.external.created, post.external.updated, post.external.deleted, account.connected, account.disconnected, account.ads.initial_sync_completed, message.received, conversation.started, call.received, call.ended, call.failed, call.permission_request, message.sent, message.edited, message.deleted, message.delivered, message.read, message.failed, reaction.received, referral.received, comment.received, review.new, review.updated, lead.received, ad.status_changed, whatsapp.template.status_updated, whatsapp.template.category_updated, whatsapp.automatic_event, whatsapp.number.activated, whatsapp.number.declined, whatsapp.number.action_required, whatsapp.number.verification_required, whatsapp.number.suspended, whatsapp.number.reactivated, whatsapp.number.released, whatsapp.number.kyc_submitted, verification.approved, verification.failed]
                   description: Events to subscribe to. Must contain at least one event if provided.
                 isActive:
                   type: boolean
@@ -23985,13 +24945,15 @@ paths:
                         metadata:
                           type: [object, "null"]
                           description: |
-                            Ad-click attribution for a conversation that started from a Meta ad.
-                            Absent when the conversation did not originate from an ad click.
-
-                            Captured from the referral Meta attaches to the first inbound message
-                            after the click, which is the only message that carries it. If the same
-                            person later clicks a different ad, the original values are kept, so the
-                            first ad wins. One exception on WhatsApp: when Meta omits `ctwa_clid`
+                            Click attribution for a conversation that started from a Meta ad or
+                            a ref-tagged ig.me / m.me link. Absent when the conversation did not
+                            originate from an attributable click.
+
+                            Captured from the referral Meta delivers for the click. If the same
+                            person later arrives through a different ad or link, the original
+                            values are kept, so the first referral wins; read the fresh referral
+                            per click on the `message.received` / `referral.received` webhooks
+                            instead. One exception on WhatsApp: when Meta omits `ctwa_clid`
                             from that referral, a later Meta automatic event can supply it and
                             refresh `ctwa_captured_at`, so treat `ctwa_captured_at` as the time
                             Zernio stored the value, not the time of the click.
@@ -24000,9 +24962,11 @@ paths:
 
                               - `ctwa_*` is WhatsApp Click-to-WhatsApp. The ad ID is
                                 `ctwa_source_id`. There is no `meta_ad_id` on WhatsApp.
-                              - `meta_ad_*` is Instagram Click-to-Direct and Facebook Messenger
-                                Click-to-Message. The ad ID is `meta_ad_id`. `ctwa_clid` never
-                                appears on these platforms.
+                              - `meta_ad_*` is Instagram Click-to-Direct, Facebook Messenger
+                                Click-to-Message, and ig.me / m.me ref links. The ad ID is
+                                `meta_ad_id` (ad clicks only; a link capture carries
+                                `meta_ad_ref` without it). `ctwa_clid` never appears on these
+                                platforms.
 
                             Every key is optional and only the keys Meta supplied are returned, so
                             read defensively. Meta does not send a campaign or ad set ID, so none
@@ -24036,16 +25000,16 @@ paths:
                               description: "WhatsApp only. When Zernio stored this referral. Always present when a WhatsApp referral was captured."
                             meta_ad_id:
                               type: string
-                              description: "Instagram and Facebook only. The Meta ad ID the user clicked. Always present when an Instagram or Facebook referral was captured."
+                              description: "Instagram and Facebook only. The Meta ad ID the user clicked. Present for ad clicks; absent when the capture came from an ig.me / m.me ref link."
                             meta_ad_source:
                               type: string
-                              description: "Instagram and Facebook only. Meta-supplied source identifier, for example ADS."
+                              description: "Instagram and Facebook only. Meta-supplied source identifier: ADS for ad clicks; SHORTLINK, SHORTLINKS or IGME-SOURCE-LINK for ref links (treat as opaque)."
                             meta_ad_type:
                               type: string
                               description: "Instagram and Facebook only. Meta-supplied referral type, for example OPEN_THREAD."
                             meta_ad_ref:
                               type: string
-                              description: "Instagram and Facebook only. The ref parameter passed through from the ad creative."
+                              description: "Instagram and Facebook only. The ref parameter passed through from the ad creative or the ig.me / m.me link."
                             meta_ad_title:
                               type: string
                               description: "Instagram and Facebook only. Title of the ad creative at click time."
@@ -24154,6 +25118,15 @@ paths:
                     already categorized at creation). Utility messages only; marketing
                     content is not allowed under this category. Accepted on the JSON
                     body only, not on multipart requests.
+                linkPreview:
+                  type: boolean
+                  default: true
+                  description: >-
+                    WhatsApp only. Set false to send the Direct Send (category: 'utility')
+                    text message without a link-preview thumbnail for the first URL in the
+                    text. Defaults to true, which is how every WhatsApp text has been sent
+                    to date. Does not apply to template sends. Accepted on the JSON body
+                    only, not on multipart requests.
                 templateLanguage:
                   type: string
                   description: WhatsApp only. Template language code (e.g. en_US).
@@ -24316,7 +25289,7 @@ paths:
         - name: cursor
           in: query
           schema: { type: string }
-          description: Pagination cursor for next page
+          description: "Opaque pagination cursor. Pass back pagination.nextCursor verbatim; do not construct one."
       responses:
         '200':
           description: Conversations containing the query, most recent match first
@@ -24384,7 +25357,7 @@ paths:
                             accountId: { type: string }
                             platform: { type: string }
         '400':
-          description: Invalid query or unsupported platform
+          description: 'Invalid query, unsupported platform, or malformed cursor'
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403':
           description: Inbox addon required
@@ -24633,7 +25606,7 @@ paths:
           in: query
           required: false
           schema: { type: string }
-          description: Opaque pagination cursor. Pass `pagination.nextCursor` from a prior response.
+          description: 'Opaque pagination cursor. Pass `pagination.nextCursor` from a prior response verbatim: a cursor we cannot parse returns 400 rather than silently restarting from the first page.'
         - name: sortOrder
           in: query
           required: false
@@ -24772,6 +25745,7 @@ paths:
                             and for inbound interactive taps `interactiveType` / `interactiveId`.
                           additionalProperties: true
                   lastUpdated: { type: string, format: date-time }
+        '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403':
           description: Inbox addon required
@@ -24822,7 +25796,7 @@ paths:
               properties:
                 accountId: { type: string, description: Social account ID }
                 message: { type: string, description: Message text }
-                attachmentUrl: { type: string, description: "URL of the attachment to send (image, video, audio, or file). The URL must be publicly accessible. For binary file uploads, use multipart/form-data instead." }
+                attachmentUrl: { type: string, description: "URL of the attachment to send (image, video, audio, or file). The URL must be publicly accessible. For binary file uploads, use multipart/form-data instead. On WhatsApp, combining an image, video, or file with `buttons` renders the media as the header of one interactive reply-button message; audio cannot be combined with buttons." }
                 category:
                   type: string
                   enum: [utility]
@@ -24840,6 +25814,14 @@ paths:
                     Utility messages only; marketing content is not allowed under
                     this category. Accepted on the JSON body only, not on multipart
                     requests.
+                linkPreview:
+                  type: boolean
+                  default: true
+                  description: >-
+                    WhatsApp only. Set false to send the message without a link-preview
+                    thumbnail for the first URL in the text. Defaults to true, which is how
+                    every WhatsApp text has been sent to date. Ignored on other platforms.
+                    Accepted on the JSON body only, not on multipart requests.
                 attachmentType:
                   type: string
                   enum: [image, video, audio, file]
@@ -24885,6 +25867,12 @@ paths:
                     reply-button message, provide `title` + `payload` and set
                     `type: postback`, e.g.
                     `{ "type": "postback", "title": "Yes", "payload": "yes" }`.
+
+                    Combine `buttons` with `attachmentUrl` and `attachmentType`
+                    `image`, `video`, or `file` to render one WhatsApp message with
+                    a media header, body text, and reply buttons. Audio is not a
+                    supported interactive header and returns 400 when combined
+                    with buttons.
                   items:
                     type: object
                     required: [type, title]
@@ -25260,6 +26248,27 @@ paths:
                           properties:
                             email: { type: string }
                             type: { type: string }
+            examples:
+              whatsappImageWithReplyButtons:
+                summary: WhatsApp image, body text, and reply buttons
+                description: |
+                  The recipient sees one WhatsApp message containing the property
+                  image as its header, "Reply yes to continue." as the body, and
+                  two tappable reply buttons labelled Yes and No. A tap arrives on
+                  the `message.received` webhook as `metadata.interactiveType:
+                  button_reply`; `metadata.interactiveId` is `btn_0` or `btn_1`.
+                value:
+                  accountId: 6a7adc04d0fe733d1a1bed76
+                  message: Reply yes to continue.
+                  attachmentUrl: https://cdn.example.com/property.jpg
+                  attachmentType: image
+                  buttons:
+                    - type: postback
+                      title: Yes
+                      payload: btn_0
+                    - type: postback
+                      title: No
+                      payload: btn_1
           multipart/form-data:
             schema:
               type: object
@@ -25270,13 +26279,13 @@ paths:
                 attachment:
                   type: string
                   format: binary
-                  description: "File attachment (images, videos, documents). Supported formats: JPEG, PNG, GIF, MP4, AAC, WAV. Max 25MB."
+                  description: "File attachment (images, videos, documents). Supported formats: JPEG, PNG, GIF, MP4, AAC, WAV. Max 25MB. On WhatsApp, combining an image, video, or document upload with buttons renders the upload as the interactive message header; audio plus buttons is rejected."
                 quickReplies:
                   type: string
                   description: JSON string of quick replies array (same schema as application/json body)
                 buttons:
                   type: string
-                  description: JSON string of buttons array (same schema as application/json body)
+                  description: JSON string of buttons array (same schema as application/json body). On WhatsApp, an accompanying image, video, or document attachment becomes the interactive message header.
                 template:
                   type: string
                   description: JSON string of template object (same schema as application/json body)
@@ -26060,8 +27069,18 @@ paths:
         (Instagram side); a row whose count can't be read is omitted.
 
         Pagination walks each account's platform listing. Following `nextCursor` reaches past
-        the first page on Facebook and Instagram only, since they are the platforms that
-        support a server-side date window; on the others the listing stops at its first page.
+        the first page on Facebook, Instagram, Threads, LinkedIn and YouTube, since they are
+        the platforms that support a server-side date window; on the others the listing stops
+        at its first page. Cursor pagination is only coherent for the default sort
+        (`sortBy=date`, `sortOrder=desc`): with `sortOrder=asc`, or with `sortBy=comments`,
+        the cursor filter does not match the sort order and the second page is unreliable.
+
+        `nextCursor` is opaque: pass it back verbatim, never construct or parse it, its
+        composition may change without notice. Because each page re-queries a live window,
+        results can still shift between requests, so dedupe by `id` on the client.
+
+        `commentCount` semantics differ by platform: YouTube's includes replies, Facebook's counts
+        top-level comments only.
       tags: [Comments]
       security: [{ bearerAuth: [] }]
       parameters:
@@ -26158,14 +27177,19 @@ paths:
       x-resource-group: "engagement"
       operationId: getInboxPostComments
       summary: Get post comments
-      description: Fetch comments for a specific post. Requires accountId query parameter.
+      description: |
+        Fetch comments for a specific post. Requires accountId query parameter.
+
+        On Facebook and Instagram, passing a COMMENT id as `postId` is also supported and
+        returns that comment's replies instead of the post's top-level comments. This is not
+        available on YouTube, where `postId` must be a video id.
       tags: [Comments]
       security: [{ bearerAuth: [] }]
       parameters:
         - name: postId
           in: path
           required: true
-          description: Zernio post ID or platform-specific post ID. Zernio IDs are auto-resolved. LinkedIn third-party posts accept full activity URN or numeric ID.
+          description: Zernio post ID or platform-specific post ID. Zernio IDs are auto-resolved. LinkedIn third-party posts accept full activity URN or numeric ID. On Facebook and Instagram, a comment ID is also accepted here and returns that comment's replies.
           schema: { type: string }
         - name: accountId
           in: query
@@ -26182,7 +27206,7 @@ paths:
         - name: cursor
           in: query
           schema: { type: string }
-          description: Pagination cursor
+          description: 'Pagination cursor, returned by a previous call as `pagination.cursor`. This is the platform''s own opaque paging value passed through verbatim: never construct, decode or validate it client-side.'
         - name: commentId
           in: query
           schema: { type: string }
@@ -26217,7 +27241,7 @@ paths:
                               enum: [blue, government, business, none]
                               description: X/Twitter verified badge type. Only present for Twitter/X comments.
                         likeCount: { type: integer }
-                        replyCount: { type: integer }
+                        replyCount: { type: integer, description: "The platform's own reply count, which includes hidden and deleted replies. Can exceed replies[].length even when repliesHasMore is false or absent." }
                         platform: { type: string, description: The platform this comment is from }
                         url:
                           type: [string, "null"]
@@ -26225,6 +27249,9 @@ paths:
                         replies:
                           type: array
                           items: { type: object }
+                        repliesHasMore:
+                          type: boolean
+                          description: "Facebook only. True when replies[] (capped at 10) does not hold the comment's full reply thread; fetch the rest by passing the comment id as postId to GET /v1/inbox/comments/{postId}. Absent (not false) on every other platform, including Instagram, which has no equivalent signal."
                         canReply: { type: boolean }
                         canDelete: { type: boolean }
                         canHide: { type: boolean, description: "Whether this comment can be hidden (Facebook, Instagram, Threads)" }
@@ -26233,7 +27260,7 @@ paths:
                         isLiked: { type: boolean, description: Whether the current user has liked this comment }
                         likeUri: { type: [string, "null"], description: Bluesky like URI for unliking }
                         cid: { type: [string, "null"], description: Bluesky content identifier }
-                        parentId: { type: [string, "null"], description: Parent comment ID for nested replies }
+                        parentId: { type: [string, "null"], description: 'ID of the parent comment. Present on entries inside replies[] for Facebook, Instagram and X/Twitter. On X/Twitter it is also present on top-level entries, where it holds the ID of the post replied to. Omitted entirely (key absent, not null) on top-level Facebook and Instagram entries and on every other platform, which express the parent relationship only through replies[] nesting.' }
                         rootUri: { type: [string, "null"], description: Bluesky root post URI }
                         rootCid: { type: [string, "null"], description: Bluesky root post CID }
                   post:
@@ -26364,6 +27391,7 @@ paths:
         - name: commentId
           in: query
           required: true
+          description: 'For LinkedIn, accepts either the numeric comment ID or the composite comment URN returned by the comments listing (e.g. urn:li:comment:(threadUrn,id))'
           schema: { type: string }
       responses:
         '200':
@@ -29007,6 +30035,15 @@ paths:
         US numbers must have an approved carrier registration
         (`/v1/sms/registrations`) before messages deliver.
 
+        **Replies and delivery status arrive as webhooks**, not by polling:
+        an inbound reply fires `message.received` with `platform: "sms"`, the
+        first message of a new thread also fires `conversation.started`, and
+        this message's own outcome fires `message.delivered` or
+        `message.failed` (the latter carrying the carrier's error code).
+
+        **Opted-out recipients:** a send to a number that replied STOP is
+        refused with `409`, never silently dropped.
+
         **Idempotency:** send an `Idempotency-Key` header to make retries safe:
         same key + same body replays the original response instead of sending a
         second message; same key + different body returns 422; a key still in
@@ -29046,9 +30083,10 @@ paths:
                   id: { type: string, description: Message ID }
                   conversationId: { type: string, description: Inbox conversation the message was threaded into. }
                   status: { type: string, enum: [sent] }
+        '400': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { description: "No SMS-enabled number matches `from`" }
-        '409': { $ref: '#/components/responses/IdempotencyKeyInFlight' }
+        '409': { description: "Recipient has opted out (replied STOP), or the same Idempotency-Key is still in flight" }
         '422': { $ref: '#/components/responses/IdempotencyKeyReused' }
         '502': { description: Carrier-side send failed }
 
@@ -30573,6 +31611,47 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { description: WhatsApp account not found }
 
+  /v1/whatsapp/account-events:
+    get:
+      x-resource-group: "accounts"
+      operationId: listWhatsAppAccountEvents
+      tags: [WhatsApp]
+      summary: List account notifications
+      description: |
+        Returns Meta-originated events recorded for a WhatsApp account, newest
+        first: template review outcomes (approved, rejected, paused, category
+        changes) and WABA status changes (restricted, disabled, reinstated,
+        disconnected). Events are captured from Meta webhooks as they happen;
+        the feed starts at the account's first recorded event and is not
+        backfilled. Complements the push events `whatsapp.template.status_updated`
+        and `account.disconnected` with a pollable history.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
+        - { name: limit, in: query, required: false, schema: { type: integer, minimum: 1, maximum: 200, default: 50 }, description: Maximum events to return }
+      responses:
+        '200':
+          description: Recorded events, newest first
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  events:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id: { type: string }
+                        type: { type: string, description: 'Event kind, e.g. template_approved, template_rejected, account_restricted, account_disconnected' }
+                        severity: { type: string, enum: [info, success, warning, critical] }
+                        title: { type: string }
+                        detail: { type: [string, "null"] }
+                        createdAt: { type: string, format: date-time }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { description: WhatsApp account not found }
   /v1/whatsapp/dataset:
     get:
       x-resource-group: "accounts"
@@ -30728,6 +31807,7 @@ paths:
                         endUserFirstName: { type: [string, "null"] }
                         endUserLastName: { type: [string, "null"] }
                         regulatoryDeclineReason: { type: [string, "null"], description: Reviewer rejection reason when status is regulatory_declined. }
+                        callingEnabled: { type: boolean, description: 'Whether WhatsApp Business Calling is enabled on this number (manage via /v1/whatsapp/phone-numbers/{id}/calling).' }
                         createdAt: { type: string, format: date-time }
                   connected:
                     type: array
@@ -30745,6 +31825,7 @@ paths:
                         displayName: { type: [string, "null"] }
                         profileId: { type: [string, "null"] }
                         connectedAt: { type: [string, "null"], format: date-time }
+                        callingEnabled: { type: boolean, description: 'Whether WhatsApp Business Calling is enabled on this number.' }
                   sandbox:
                     type: [object, "null"]
                     description: |
@@ -31267,6 +32348,7 @@ paths:
                         endUserFirstName: { type: [string, "null"] }
                         endUserLastName: { type: [string, "null"] }
                         regulatoryDeclineReason: { type: [string, "null"], description: Reviewer rejection reason when status is regulatory_declined. }
+                        callingEnabled: { type: boolean, description: 'Whether WhatsApp Business Calling is enabled on this number (manage via /v1/whatsapp/phone-numbers/{id}/calling).' }
                         createdAt: { type: string, format: date-time }
                   connected:
                     type: array
@@ -31284,6 +32366,7 @@ paths:
                         displayName: { type: [string, "null"] }
                         profileId: { type: [string, "null"] }
                         connectedAt: { type: [string, "null"], format: date-time }
+                        callingEnabled: { type: boolean, description: 'Whether WhatsApp Business Calling is enabled on this number.' }
                   sandbox:
                     type: [object, "null"]
                     description: |
@@ -31643,6 +32726,7 @@ paths:
                                   label: { type: string }
                                   value: { type: string }
                                   documentId: { type: string, description: 'Present on document rows — the Telnyx document id. GET /v1/whatsapp/phone-numbers/kyc/document/{documentId} streams it (auth-scoped, inline PDF).' }
+                  pendingReview: { type: boolean, description: 'true when this account already has a number for this country in regulatory review (status pending_regulatory). Scope is the whole account across all profiles, and the country only (any number type), so it is not a per-end-client signal on a multi-tenant setup. Informational only: it never blocks a submission, and several same-country numbers may sit in review at once. For a per-end-client view, call GET /v1/phone-numbers with `profileId` and `status=pending_regulatory`; that view also lists numbers declined in the last 30 days.' }
         '400': { description: Country not available }
         '401': { $ref: '#/components/responses/Unauthorized' }
     post:
@@ -31680,7 +32764,7 @@ paths:
               properties:
                 profileId: { type: string }
                 country: { type: string }
-                submissionId: { type: string, description: Idempotency token for this submission attempt. A retry/double-submit with the same token returns the same number; omit and each call creates a new number. }
+                submissionId: { type: string, description: 'Idempotency token for this submission attempt. Once the number has been ordered, a retry with the same token returns that same number instead of ordering another. A submission that fails before the number is ordered releases the token, so you can correct your details and re-submit with it. Omit it and every call provisions a new number.' }
                 quantity: { type: integer, minimum: 1, maximum: 5, default: 1, description: 'Provision several same-country numbers from one submission (1-5). The single verification covers all of them; each number is billed only when it activates. Numbers that fail to order are skipped (best-effort). With `areaCode`, a quantity above that area''s live stock is rejected with a 400.' }
                 reuse: { type: boolean, description: Reuse a prior approved verification for this country (skips document/field collection; places the order immediately). }
                 reuseOptionId: { type: string, description: 'Which reusable verification to use (GET reusable.options[].id). The unambiguous selection key. Omitted = the approved default. No match = 409.' }
@@ -31717,6 +32801,7 @@ paths:
                     first_name: { type: string }
                     last_name: { type: string }
                     street_address: { type: string }
+                    extended_address: { type: string, description: 'Address complement: apartment, suite, unit, or the quadra/lote used in some countries. Optional. Does not substitute for a building number on street_address.' }
                     locality: { type: string }
                     administrative_area: { type: string }
                     postal_code: { type: string }
@@ -31841,6 +32926,7 @@ paths:
               properties:
                 country: { type: string, minLength: 2, maxLength: 2, description: ISO 3166-1 alpha-2 country code. }
                 street_address: { type: string }
+                extended_address: { type: string, description: 'Address complement: apartment, suite, unit, or the quadra/lote used in some countries. Optional. Does not substitute for a building number on street_address.' }
                 locality: { type: string, description: City / town. }
                 administrative_area: { type: string, description: "State / province / region. When omitted, the pre-check is skipped (the final submit still validates)." }
                 postal_code: { type: string }
@@ -32629,6 +33715,7 @@ paths:
                                   label: { type: string }
                                   value: { type: string }
                                   documentId: { type: string, description: 'Present on document rows — the Telnyx document id. GET /v1/whatsapp/phone-numbers/kyc/document/{documentId} streams it (auth-scoped, inline PDF).' }
+                  pendingReview: { type: boolean, description: 'true when this account already has a number for this country in regulatory review (status pending_regulatory). Scope is the whole account across all profiles, and the country only (any number type), so it is not a per-end-client signal on a multi-tenant setup. Informational only: it never blocks a submission, and several same-country numbers may sit in review at once. For a per-end-client view, call GET /v1/phone-numbers with `profileId` and `status=pending_regulatory`; that view also lists numbers declined in the last 30 days.' }
         '400': { description: Country not available }
         '401': { $ref: '#/components/responses/Unauthorized' }
     post:
@@ -32670,7 +33757,7 @@ paths:
               properties:
                 profileId: { type: string }
                 country: { type: string }
-                submissionId: { type: string, description: Idempotency token for this submission attempt. A retry/double-submit with the same token returns the same number; omit and each call creates a new number. }
+                submissionId: { type: string, description: 'Idempotency token for this submission attempt. Once the number has been ordered, a retry with the same token returns that same number instead of ordering another. A submission that fails before the number is ordered releases the token, so you can correct your details and re-submit with it. Omit it and every call provisions a new number.' }
                 quantity: { type: integer, minimum: 1, maximum: 5, default: 1, description: 'Provision several same-country numbers from one submission (1-5). The single verification covers all of them; each number is billed only when it activates. Numbers that fail to order are skipped (best-effort). With `areaCode`, a quantity above that area''s live stock is rejected with a 400.' }
                 reuse: { type: boolean, description: Reuse a prior approved verification for this country (skips document/field collection; places the order immediately). }
                 reuseOptionId: { type: string, description: 'Which reusable verification to use (GET reusable.options[].id). The unambiguous selection key. Omitted = the approved default. No match = 409.' }
@@ -32707,6 +33794,7 @@ paths:
                     first_name: { type: string }
                     last_name: { type: string }
                     street_address: { type: string }
+                    extended_address: { type: string, description: 'Address complement: apartment, suite, unit, or the quadra/lote used in some countries. Optional. Does not substitute for a building number on street_address.' }
                     locality: { type: string }
                     administrative_area: { type: string }
                     postal_code: { type: string }
@@ -32810,6 +33898,7 @@ paths:
               properties:
                 country: { type: string, minLength: 2, maxLength: 2, description: ISO 3166-1 alpha-2 country code. }
                 street_address: { type: string }
+                extended_address: { type: string, description: 'Address complement: apartment, suite, unit, or the quadra/lote used in some countries. Optional. Does not substitute for a building number on street_address.' }
                 locality: { type: string, description: City / town. }
                 administrative_area: { type: string, description: "State / province / region. When omitted, the pre-check is skipped (the final submit still validates)." }
                 postal_code: { type: string }
@@ -35588,7 +36677,7 @@ paths:
                         contactId: { type: string }
                         channelId: { type: string }
                         platformIdentifier: { type: string }
-                        contactName: { type: string }
+                        contactName: { type: [string, "null"] }
                         status: { type: string, enum: [pending, sent, delivered, read, failed] }
                         messageId: { type: string }
                         error: { type: string }
@@ -35623,7 +36712,7 @@ paths:
             schema:
               type: object
               properties:
-                contactIds: { type: array, items: { type: string }, description: Specific contact IDs to add }
+                contactIds: { type: array, items: { type: string }, description: 'Specific contact IDs to add. Zernio contact ids (24-character hex), as returned by the list-contacts endpoint. A platform identifier such as a WhatsApp wa_id is rejected with 400; use phones for raw numbers.' }
                 phones: { type: array, items: { type: string }, maxItems: 20000, description: Raw phone numbers (auto-creates contacts). Useful for WhatsApp/Telegram manual entry }
                 useSegment: { type: boolean, description: Auto-populate from broadcast segment filters }
       responses:
@@ -36572,10 +37661,10 @@ paths:
                         contactName: { type: string }
                         currentStepIndex: { type: integer }
                         status: { type: string, enum: [active, completed, exited, paused] }
-                        exitReason: { type: string }
-                        nextStepAt: { type: string, format: date-time }
+                        exitReason: { type: [string, "null"] }
+                        nextStepAt: { type: [string, "null"], format: date-time }
                         stepsSent: { type: integer }
-                        lastStepSentAt: { type: string, format: date-time }
+                        lastStepSentAt: { type: [string, "null"], format: date-time }
                         createdAt: { type: string, format: date-time }
                   pagination:
                     type: object
@@ -37104,7 +38193,7 @@ paths:
                   - type: object
                     required: [backfillPending]
                     properties:
-                      backfillPending: { type: boolean, const: true }
+                      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': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403':
@@ -37168,6 +38257,130 @@ paths:
         '429': { description: "Google Ads operations budget exhausted; retry later." }
         '501': { description: Only available on Google Ads accounts }
 
+  /v1/ads/local-services/leads:
+    get:
+      x-resource-group: "ads"
+      operationId: listLocalServicesLeads
+      tags: ["Ad Insights"]
+      x-platforms: ["google"]
+      summary: Google Local Services Ads leads
+      description: |-
+        Leads generated by Local Services Ads (phone calls, messages, bookings),
+        read live from Google's `local_services_lead` resource, newest first.
+        No persistence: Google is the source of truth and lead/credit statuses
+        keep changing server-side. Google never returns healthcare-category
+        leads, and `WIPED_OUT` leads arrive with contact erased (`contact` is
+        null). Draws on the shared Google Ads operations budget.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Google ads SocialAccount id." }
+        - { name: customerId, in: query, schema: { type: string }, description: "Numeric Google Ads customer id (no dashes). Defaults to the account's connected customer." }
+        - { name: fromDate, in: query, schema: { type: string, format: date }, description: "Leads created at/after this day." }
+        - { name: toDate, in: query, schema: { type: string, format: date }, description: "Leads created at/before this day." }
+        - { name: leadType, in: query, schema: { type: string, enum: [PHONE_CALL, MESSAGE, BOOKING] } }
+        - { name: leadStatus, in: query, schema: { type: string }, description: "Google LocalServicesLeadStatus enum value (e.g. NEW, BOOKED, WIPED_OUT)." }
+        - { name: chargedOnly, in: query, schema: { type: boolean }, description: "true = only leads Google charged for." }
+        - { name: pageToken, in: query, schema: { type: string }, description: "Cursor from paging.nextPageToken of the previous page." }
+      responses:
+        '200':
+          description: Local Services leads
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  customerId: { type: string }
+                  data:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id: { type: [string, "null"], description: "Lead id; pass to /v1/ads/local-services/leads/{leadId}/conversations." }
+                        leadType: { type: [string, "null"], description: "PHONE_CALL / MESSAGE / BOOKING." }
+                        categoryId: { type: [string, "null"] }
+                        serviceId: { type: [string, "null"] }
+                        contact:
+                          type: [object, "null"]
+                          description: "Null for WIPED_OUT leads (contact erased by Google)."
+                          properties:
+                            consumerName: { type: [string, "null"] }
+                            email: { type: [string, "null"] }
+                            phoneNumber: { type: [string, "null"] }
+                        status: { type: [string, "null"] }
+                        createdTime: { type: [string, "null"], description: "Google datetime in the customer's timezone (YYYY-MM-DD HH:MM:SS)." }
+                        locale: { type: [string, "null"] }
+                        charged: { type: boolean }
+                        creditState: { type: [string, "null"] }
+                        creditStateLastUpdate: { type: [string, "null"] }
+                  paging:
+                    type: object
+                    properties:
+                      nextPageToken: { type: [string, "null"], description: "Null when the last page was returned." }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '429': { description: "Google Ads operations budget exhausted; retry later." }
+        '501': { description: Only available on Google Ads accounts }
+
+  /v1/ads/local-services/leads/{leadId}/conversations:
+    get:
+      x-resource-group: "ads"
+      operationId: listLocalServicesLeadConversations
+      tags: ["Ad Insights"]
+      x-platforms: ["google"]
+      summary: Conversations of a Local Services lead
+      description: |-
+        Conversation entries of one Local Services lead: phone calls (duration,
+        recording URL) and messages (text, attachment URLs), oldest first. Read
+        live from `local_services_lead_conversation`, always scoped to a single
+        lead. Call-recording URLs require read access on the Google Ads account.
+        Draws on the shared Google Ads operations budget.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: leadId, in: path, required: true, schema: { type: string }, description: "Numeric lead id from /v1/ads/local-services/leads." }
+        - { 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: pageToken, in: query, schema: { type: string }, description: "Cursor from paging.nextPageToken of the previous page." }
+      responses:
+        '200':
+          description: Lead conversations
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  customerId: { type: string }
+                  data:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id: { type: [string, "null"] }
+                        channel: { type: [string, "null"], description: "PHONE_CALL / MESSAGE / SMS / EMAIL / WHATSAPP / ADS_API." }
+                        participantType: { type: [string, "null"], description: "ADVERTISER or CONSUMER." }
+                        eventDateTime: { type: [string, "null"] }
+                        phoneCall:
+                          type: [object, "null"]
+                          description: "Only on PHONE_CALL entries."
+                          properties:
+                            callDurationMillis: { type: [integer, "null"] }
+                            callRecordingUrl: { type: [string, "null"] }
+                        message:
+                          type: [object, "null"]
+                          description: "Only on message-channel entries."
+                          properties:
+                            text: { type: [string, "null"] }
+                            attachmentUrls: { type: array, items: { type: string } }
+                  paging:
+                    type: object
+                    properties:
+                      nextPageToken: { type: [string, "null"], description: "Null when the last page was returned." }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '429': { description: "Google Ads operations budget exhausted; retry later." }
+        '501': { description: Only available on Google Ads accounts }
+
   /v1/ads/keywords:
     get:
       x-resource-group: "ads"
@@ -37272,6 +38485,8 @@ paths:
         - { name: profileId, in: query, schema: { type: string }, description: Profile ID }
         - { name: fromDate, in: query, schema: { type: string, format: date }, description: "Start of metrics date range (YYYY-MM-DD, inclusive). Defaults to 90 days ago when both date params are omitted." }
         - { name: toDate, in: query, schema: { type: string, format: date }, description: "End of metrics date range (YYYY-MM-DD, inclusive). Defaults to today. Max 730-day range." }
+        - { name: hasDelivery, in: query, schema: { type: boolean }, description: "Return only campaigns that delivered between `fromDate` and `toDate` — spend above zero, or impressions served at zero spend. Unlike `status`, which reads a campaign's CURRENT state, this filters on what happened inside the window. Filters the campaign set itself, so `pagination.total` counts only matching campaigns. Mirrors the same filter on /v1/ads/tree." }
+        - { name: minSpend, in: query, schema: { type: number, minimum: 0 }, description: "Return only campaigns whose spend between `fromDate` and `toDate` reaches this amount, in each campaign's OWN currency (the `currency` field on the campaign). Implies `hasDelivery`; `minSpend=0` applies no filter. Mirrors the same filter on /v1/ads/tree." }
       responses:
         '200':
           description: Paginated campaigns
@@ -37367,8 +38582,20 @@ paths:
       x-platforms: ["meta", "google", "tiktok", "linkedin", "pinterest", "x", "openai"]
       summary: Pause or resume a campaign
       description: |
-        Updates the status of all ads in a campaign. Makes one platform API call (not per-ad) since status cascades through the campaign hierarchy.
-        Ads in terminal statuses (rejected, completed, cancelled) are automatically skipped.
+        Writes the campaign's own on/off switch, then lets the platform cascade delivery to its ad sets and ads.
+        Makes one platform API call, not one per ad.
+
+        The switch is always written, whatever delivery status the ads underneath report: an ad still in review
+        does not block resuming its campaign. The echoed `status` is the confirmation that it landed.
+
+        `updated` / `skipped` describe only the ads whose own stored status CHANGED alongside it, so
+        `updated: 0` is a normal successful response, not a no-op. Ads are skipped when they are in a terminal
+        status (rejected, completed, cancelled), already in the target state, or switched on but not yet
+        delivering — the last group keeps its `pending_review` / `error` status until the platform reports what
+        it became. `skippedReasons` names which case applies.
+
+        On Meta this flips the campaign only. An ad set paused in its own right stays paused, so pair this with
+        PUT /v1/ads/ad-sets/{adSetId}/status when you also need the ad set switched back on.
       security:
         - bearerAuth: []
       parameters:
@@ -37391,10 +38618,10 @@ paths:
               schema:
                 type: object
                 properties:
-                  updated: { type: integer, description: Number of ads updated }
-                  skipped: { type: integer, description: Number of ads skipped }
-                  skippedReasons: { type: array, items: { type: string } }
-                  message: { type: string, description: Human-readable summary (present when no ads were actionable) }
+                  status: { type: string, enum: [active, paused], description: The status written to the campaign }
+                  updated: { type: integer, description: 'Number of ads whose own stored status changed too. 0 is normal on a resume whose ads are all awaiting the platform.' }
+                  skipped: { type: integer, description: 'Number of ads whose own status was left as it was' }
+                  skippedReasons: { type: array, items: { type: string }, description: 'Why each group of ads was skipped' }
         '400':
           description: Invalid input or campaign spans multiple social accounts
         '401': { $ref: '#/components/responses/Unauthorized' }
@@ -37897,7 +39124,7 @@ paths:
                   properties:
                     amount: { type: number }
                     type: { type: string, enum: [daily, lifetime] }
-                status: { type: string, enum: [active, paused], description: Omit if not toggling delivery state }
+                status: { type: string, enum: [active, paused], description: "Writes the ad set's own on/off switch (Meta: `configured_status`) on Meta and LinkedIn, whatever delivery status its ads report. Omit if not toggling delivery state." }
                 name: { type: string, maxLength: 255, description: "Rename the ad set (Meta only; other platforms return 501). At least one of budget/status/bidStrategy/name is required." }
                 bidStrategy:
                   allOf: [{ $ref: '#/components/schemas/BidStrategy' }]
@@ -37976,9 +39203,11 @@ paths:
                 properties:
                   budget: { $ref: '#/components/schemas/AdBudget' }
                   budgetLevel: { type: string, enum: [adset] }
-                  status: { type: string, enum: [active, paused] }
-                  statusUpdated: { type: integer }
-                  statusSkipped: { type: integer }
+                  status: { type: string, enum: [active, paused], description: 'The status written to the ad set. Absent when nothing was written (see statusMessage).' }
+                  statusUpdated: { type: integer, description: 'Number of ads whose own stored status changed alongside the ad set switch' }
+                  statusSkipped: { type: integer, description: 'Number of ads whose own status was left as it was' }
+                  statusSkippedReasons: { type: array, items: { type: string }, description: 'Why each group of ads was skipped' }
+                  statusMessage: { type: string, description: 'Present only where the platform has no ad-set switch and no child ad was actionable; `status` is then absent because nothing was written' }
                   bidStrategy: { $ref: '#/components/schemas/BidStrategy' }
                   bidAmount: { type: [number, "null"] }
                   roasAverageFloor: { type: [number, "null"] }
@@ -38002,6 +39231,23 @@ paths:
         over PUT /v1/ads/ad-sets/{adSetId} for callers that only want the
         status toggle and prefer a symmetric URL to
         /v1/ads/campaigns/{campaignId}/status.
+
+        On Meta and LinkedIn this writes the ad set's own on/off switch
+        (Meta: `configured_status`), whatever delivery status its ads report —
+        an ad still in review does not block resuming its ad set. The echoed
+        `status` is the confirmation that it landed. Where the platform has no
+        ad-set switch (TikTok and others) the toggle is emulated by flipping the
+        child ads; a call with no actionable ad then writes nothing and returns a
+        `message` with no `status`.
+
+        `updated` / `skipped` describe only the ads whose own stored status
+        CHANGED alongside the switch, so `updated: 0` is a normal successful
+        response. See `skippedReasons` for which of the three cases applies
+        (terminal, already in the target state, or switched on but not yet
+        delivering).
+
+        A campaign created paused needs its campaign resumed as well: pair this
+        with PUT /v1/ads/campaigns/{campaignId}/status.
       security:
         - bearerAuth: []
       parameters:
@@ -38024,8 +39270,11 @@ paths:
               schema:
                 type: object
                 properties:
-                  updated: { type: integer }
-                  skipped: { type: integer }
+                  status: { type: string, enum: [active, paused], description: 'The status written to the ad set. Absent when nothing was written (see message).' }
+                  updated: { type: integer, description: 'Number of ads whose own stored status changed too. 0 is normal on a resume whose ads are all awaiting the platform.' }
+                  skipped: { type: integer, description: 'Number of ads whose own status was left as it was' }
+                  skippedReasons: { type: array, items: { type: string }, description: 'Why each group of ads was skipped' }
+                  message: { type: string, description: 'Present only where the platform has no ad-set switch and no child ad was actionable' }
         '400': { description: Invalid input }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { description: Ad set not found }
@@ -38068,8 +39317,10 @@ paths:
         - { name: accountId, in: query, schema: { type: string }, description: Social account ID }
         - { name: profileId, in: query, schema: { type: string }, description: Profile ID }
         - { name: campaignId, in: query, schema: { type: string }, description: "Restrict the tree to a single campaign by its platform campaign id (the id the platform assigns, e.g. Meta's numeric campaign id). Filters the campaign set itself, so it works regardless of account size and pagination — pass this when you already hold a campaign id instead of paging the tree to find it. Mirrors the `campaignId` filter on GET /v1/ads." }
-        - { name: fromDate, in: query, schema: { type: string, format: date }, description: "Start of the METRICS date range (YYYY-MM-DD). Affects only the spend/impression numbers overlaid on each node, NOT which campaigns are returned. Defaults to 90 days ago." }
+        - { name: fromDate, in: query, schema: { type: string, format: date }, description: "Start of the METRICS date range (YYYY-MM-DD). On its own it affects only the spend/impression numbers overlaid on each node, not which campaigns are returned — pass `hasDelivery` or `minSpend` to also filter the campaign set to this window. Defaults to 90 days ago." }
         - { name: toDate, in: query, schema: { type: string, format: date }, description: "End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range." }
+        - { name: hasDelivery, in: query, schema: { type: boolean }, description: "Return only campaigns that delivered between `fromDate` and `toDate` — spend above zero, or impressions served at zero spend. Unlike `status`, which reads a campaign's CURRENT state, this filters on what happened inside the window, so a campaign that spent then and is paused today is still returned. Filters the campaign set itself, so `pagination.total` counts only matching campaigns." }
+        - { name: minSpend, in: query, schema: { type: number, minimum: 0 }, description: "Return only campaigns whose spend between `fromDate` and `toDate` reaches this amount. Expressed in each campaign's OWN currency (the `currency` field on the campaign node): spend is stored per ad account in its native currency and one response can span several. Implies `hasDelivery`; `minSpend=0` applies no filter." }
         - { name: sort, in: query, schema: { type: string, enum: [newest, oldest, spend_desc, spend_asc], default: newest }, description: "Campaign-level sort order. `newest` (default) / `oldest` order by the campaign's newest-ad createdAt. `spend_desc` / `spend_asc` order by aggregated spend in the requested date range; campaigns with no spend land at the end." }
         - { name: timeIncrement, in: query, schema: { type: integer, enum: [1] }, description: "Set to `1` to also return a daily breakdown. Mirrors Meta Insights' `time_increment=1`: each node gains a `daily[]` array of per-day metrics (same fields as the aggregated `metrics`) alongside the range total, so you get per-entity daily trends in ONE call instead of calling the tree once per day. Only `1` (daily) is supported. The daily series covers the same date range and uses the same source data as `metrics`, except `reach` on Meta and TikTok: the range total is the platform's de-duplicated value, so daily reach does not sum to it. See `dailyLevel` to control which levels carry it." }
         - { name: dailyLevel, in: query, schema: { type: string, enum: [campaign, adset, ad], default: campaign }, description: "Which tree levels get the `daily[]` series when `timeIncrement=1`. `campaign` (default) attaches it on campaign nodes only — the common per-campaign-trend case, and the smallest payload. `adset` adds it on ad sets too; `ad` adds it on every ad in `ads[]` as well (heaviest — a long range × up to 100 ads per ad set). Scope with `campaignId` to keep `ad`-level responses small. Ignored when `timeIncrement` is unset." }
@@ -38092,7 +39343,7 @@ paths:
                   - type: object
                     required: [backfillPending]
                     properties:
-                      backfillPending: { type: boolean, const: true }
+                      backfillPending: { type: boolean, description: 'Always true on this response. Part of the requested range is still being backfilled; retry until the request returns 200.' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403':
           description: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.
@@ -38145,7 +39396,7 @@ paths:
                   - type: object
                     required: [backfillPending]
                     properties:
-                      backfillPending: { type: boolean, const: true }
+                      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': { $ref: '#/components/responses/BadRequest' }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403':
@@ -38294,6 +39545,7 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { $ref: '#/components/responses/NotFound' }
         '501': { description: "targeting or creative not supported on the platform (Meta + TikTok only)" }
+        '502': { description: "Meta accepted the request then failed to produce the media (upload session, chunk transfer, processing timeout, or a response with no image hash). Inspect `platformError.reason`." }
     delete:
       x-resource-group: "ads"
       operationId: deleteAd
@@ -38417,7 +39669,7 @@ paths:
                   - type: object
                     required: [backfillPending]
                     properties:
-                      backfillPending: { type: boolean, const: true }
+                      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:
@@ -38849,7 +40101,7 @@ paths:
                   - type: object
                     required: [backfillPending]
                     properties:
-                      backfillPending: { type: boolean, const: true }
+                      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:
@@ -38960,6 +40212,7 @@ paths:
         '404': { description: "Ad not found" }
         '405': { description: "Platform has no click-URL tracking surface" }
         '422': { description: "Meta creative cannot be rebuilt (e.g. placement-customized/asset-feed/dark creative)" }
+        '502': { description: "Meta accepted the request then failed to produce the media (upload session, chunk transfer, processing timeout, or a response with no image hash). Inspect `platformError.reason`." }
   /v1/ads/{adId}/comments:
     get:
       x-resource-group: "engagement"
@@ -39584,6 +40837,7 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '422': { description: No Facebook Page found to act as the story actor }
         '501': { description: Only supported on Meta (facebook/instagram) }
+        '502': { description: "Meta accepted the request then failed to produce the media (upload session, chunk transfer, processing timeout, or a response with no image hash). Inspect `platformError.reason`." }
 
   /v1/ads/creatives/{creativeId}:
     get:
@@ -40191,8 +41445,20 @@ paths:
 
         `instagramAccountId`, `destinationType` and `adSetId` are Meta-only and
         return 400 on other platforms.
+
+        **Retries.** Boosts are NOT idempotent and can take minutes when Meta requires re-hosting an
+        Instagram video, so do not retry on client timeout. Send an
+        Idempotency-Key header to make retries safe: same key and body replays
+        the original 201, and distinct keys always create distinct ads.
+        Without the header, an identical request is treated as a retry: while
+        one is in flight it returns 409, and within 10 minutes of a completed
+        boost it returns the already-created ad instead of creating another.
+        To intentionally duplicate an ad, send distinct Idempotency-Keys (or
+        vary the body, e.g. the name).
       security:
         - bearerAuth: []
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKeyHeader'
       requestBody:
         required: true
         content:
@@ -40217,7 +41483,7 @@ paths:
                     type: { type: string, enum: [daily, lifetime] }
                 instagramAccountId: { type: string, description: "Meta only. Instagram identity the ad runs AS (creative.instagram_user_id), overriding the account linked to the Page. Live-verified against a Page-post creative." }
                 destinationType: { type: string, enum: [INSTAGRAM_PROFILE, WEBSITE, ON_AD, MESSENGER, WHATSAPP], description: "Meta only. Ad-set destination_type — where the click LANDS, as opposed to instagramAccountId which is who the ad runs as. Lead ads force ON_AD and ignore this." }
-                currency: { type: string, example: USD }
+                currency: { type: string, minLength: 3, maxLength: 3, example: USD, description: "ISO 4217 currency code matching the ad account's currency. Meta only. Optional: Zernio resolves it from the ad account when omitted. The value selects the minor-unit exponent Zernio converts budget/bid amounts by before calling Meta (most currencies are cents; zero-decimal currencies like JPY/KRW are sent as-is)." }
                 schedule:
                   type: object
                   properties:
@@ -40406,8 +41672,9 @@ paths:
                     CTA button label. Send it together with `linkUrl` — a CTA without a
                     destination produces a button that goes nowhere, so sending one alone is a 400.
 
-                    **Meta**: validated against the Meta CTA enum (same values as
-                    POST /v1/ads/create), e.g. `LEARN_MORE`, `SHOP_NOW`, `SIGN_UP`.
+                    **Meta**: the CTA enum of POST /v1/ads/create plus
+                    `VIEW_INSTAGRAM_PROFILE`, which is accepted on boost only. For that
+                    value `linkUrl` is typically the Instagram profile URL.
 
                     **TikTok**: pass-through to `call_to_action` on the Spark Ad creative; the
                     platform validates the value. See TikTok's "Enumeration - Call-to-Action".
@@ -40462,6 +41729,10 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403':
           description: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.
+        '409':
+          description: |
+            An identical boost request is already in progress (with or without
+            an Idempotency-Key). Wait for it to finish instead of retrying.
         '422':
           description: |
             Platform ads connection required (TikTok Ads, X Ads), missing linked
@@ -40469,13 +41740,15 @@ paths:
             as an Identity on the target advertiser. Returned with code
             `ads_connection_required`; the message includes the actionable
             "TikTok Ads Manager → Assets → Identity" remediation step.
+            Also returned as `idempotency_key_reused` when an Idempotency-Key
+            is reused with a different request body.
 
   /v1/ads/create:
     post:
       x-resource-group: "ads"
       operationId: createStandaloneAd
       tags: ["Ad Campaigns"]
-      x-platforms: ["meta", "google", "tiktok", "linkedin", "pinterest", "x"]
+      x-platforms: ["meta", "google", "tiktok", "linkedin", "pinterest", "x", "openai"]
       summary: Create standalone ad
       description: >-
         Creates a paid ad with custom creative across Meta, Google Ads,
@@ -40580,7 +41853,11 @@ paths:
                 status:
                   type: string
                   enum: [ACTIVE, PAUSED]
-                  description: "Meta and TikTok. Publish state of the created entities. Omitted or ACTIVE publishes live (default, back-compat); PAUSED creates them paused and skips activation, so you can review before they spend. On TikTok the whole campaign > ad group > ad hierarchy stays paused."
+                  description: "Meta and TikTok. Publish state of the created entities. Omitted or ACTIVE publishes live (default, back-compat); PAUSED creates them paused so you can review before they spend. On Meta the pause is held on the campaign this call creates, leaving the ad set and ad switched on, so a single PUT /v1/ads/campaigns/{campaignId}/status with `active` brings the whole thing live. It is held at every level instead when the pause cannot rely on the campaign: `existingCampaignId` (that campaign may be running and is never touched) or `campaignStatus: ACTIVE`. On TikTok the whole campaign > ad group > ad hierarchy stays paused."
+                campaignStatus:
+                  type: string
+                  enum: [ACTIVE, PAUSED]
+                  description: "Meta only. Overrides `status` for the campaign level alone, so you can create a live campaign whose ad set and ad stay paused, or the reverse. Omitted, it follows `status`."
                 budgetLevel:
                   type: string
                   enum: [adset, campaign]
@@ -40594,7 +41871,7 @@ paths:
                         across ad sets automatically.
                     Meta requires the budget at exactly one level, never both. Non-Meta platforms ignore
                     this field. Ignored on the attach shape (`adSetId`), which inherits the existing budget.
-                currency: { type: string }
+                currency: { type: string, minLength: 3, maxLength: 3, description: "ISO 4217 currency code matching the ad account's currency (e.g. `USD`). Meta only. Optional: Zernio resolves it from the ad account when omitted. The value selects the minor-unit exponent Zernio converts budget/bid amounts by before calling Meta (most currencies are cents; zero-decimal currencies like JPY/KRW are sent as-is)." }
                 headline: { type: string, description: "Required for Meta, Google, Pinterest, LinkedIn, and OpenAI Ads on legacy + attach shapes (skip for multi-creative — use `creatives[].headline`). Ignored for TikTok and X/Twitter. Max: Meta=255, Google=30, Pinterest=100, LinkedIn=400, OpenAI=50 (min 3). On LinkedIn this is the ad's headline (the bold text on the creative); for traffic ads it's the link card title. On OpenAI Ads this is the chat card's title." }
                 longHeadline: { type: string, maxLength: 90, description: "Google Display only — defaults to `headline` if omitted. On LinkedIn, reused as the optional secondary description text on traffic (link) ads; omitted if not provided." }
                 body: { type: string, description: "Required on legacy + attach shapes. For X/Twitter this is the tweet text (max 280 chars including a ~24-char URL when `linkUrl` is set). On LinkedIn this is the post commentary (the intro text shown above the ad). On OpenAI Ads this is the chat card's body text. Max: Google=90, Pinterest=500, OpenAI=100." }
@@ -40615,7 +41892,7 @@ paths:
                   properties:
                     url: { type: string, format: uri, description: "Public URL of the video. Meta: uploaded via chunked transfer on /act_X/advideos, then the request blocks on Meta's transcoding until status.video_status === 'ready'. LinkedIn: uploaded via the Videos API (multipart), then the request blocks until LinkedIn finishes transcoding (status AVAILABLE) — short clips take ~10-30s. Provide either `url` or `id`."}
                     id: { type: string, description: "Meta only. Reuse a video ALREADY uploaded to this ad account instead of re-uploading the file: pass the `videoId` returned by a previous create. Wins over `url`, so N ads that differ only in copy share one upload (`existingCreativeId` only covers the identical-copy case). Provide either `url` or `id`."}
-                    thumbnailUrl: { type: string, format: uri, description: "Public URL of a still-image thumbnail for the video. OPTIONAL: when omitted on Meta, the poster is auto-generated from Meta's own preferred video thumbnail (the same candidates Ads Manager shows), so video ads publish without supplying one. Provide it to control the poster frame exactly (uploaded as an ad image and referenced in object_story_spec.video_data). Ignored by LinkedIn (auto-generated poster frame)." }
+                    thumbnailUrl: { type: string, format: uri, description: "Public URL of a still-image thumbnail for the video. OPTIONAL: when omitted on Meta, the poster is auto-generated from Meta's own preferred video thumbnail (the same candidates Ads Manager shows), so video ads usually publish without supplying one. When Meta produces no candidate the request fails with a 502 platform_error (reason: video_thumbnail_unavailable) — retry, or supply this field. Provide it to control the poster frame exactly (uploaded as an ad image and referenced in object_story_spec.video_data). Ignored by LinkedIn (auto-generated poster frame)." }
                 creatives:
                   type: array
                   minItems: 1
@@ -40636,7 +41913,7 @@ paths:
                       imageUrl: { type: string, format: uri, description: "Image creative. Mutually exclusive with `video`." }
                       video:
                         type: object
-                        description: "Video creative for this entry. Mutually exclusive with `imageUrl`. thumbnailUrl is optional — when omitted, the poster is auto-generated from Meta's preferred video thumbnail."
+                        description: "Video creative for this entry. Mutually exclusive with `imageUrl`. thumbnailUrl is optional: when omitted, the poster is auto-generated from Meta's preferred video thumbnail, and the request fails with a 502 platform_error (reason: video_thumbnail_unavailable) if Meta produces no candidate."
                         required: [url]
                         properties:
                           url: { type: string, format: uri }
@@ -40657,8 +41934,9 @@ paths:
                     The attached ad takes the full single-creative surface:
                     `headline`/`body`/`description`/`callToAction` plus either
                     `imageUrl`/`video` OR `placementAssets` (its own per-placement
-                    Feed/Story assets), and `leadGenFormId` when the target is a
-                    lead ad set (the parent must be ON_AD — true for ad sets
+                    Feed/Story assets) OR `translations`/`defaultLocale` (its own
+                    per-locale asset feed, Meta only), and `leadGenFormId` when
+                    the target is a lead ad set (the parent must be ON_AD, true for ad sets
                     created via goal `lead_generation`; Meta rejects a formless ad
                     there, so pass the form on EVERY attached ad). This is the way
                     to build N full ads sharing one ad set: create the first ad
@@ -40887,8 +42165,9 @@ paths:
                   description: |
                     Meta only. Override the Instagram account the ad is delivered as — pass an Instagram
                     Business Account ID (e.g. 17841...), mapped to the creative's `instagram_user_id`.
-                    When omitted we auto-resolve the IG account linked to the connected Facebook Page
-                    (the existing default). Useful when a Page has more than one eligible IG account.
+                    When omitted we use the Instagram actor Meta already runs the Page's other ads as,
+                    falling back to the Page's page-backed Instagram account. Useful when a Page has more
+                    than one eligible IG account.
                 dynamicCreative:
                   type: object
                   description: |
@@ -40998,8 +42277,8 @@ paths:
                     works on a normal ad may be rejected with "The following images have invalid
                     dimensions for Dynamic Creative" (subcode 1885558). Video is not affected.
 
-                    Mutually exclusive with `dynamicCreative`, `placementAssets`, `carouselCards` and
-                    `existingCreativeId` — Meta allows one `asset_feed_spec` shape per creative.
+                    Mutually exclusive with `dynamicCreative`, `placementAssets`, `carouselCards`,
+                    `existingCreativeId` and `creatives[]`. Meta allows one `asset_feed_spec` shape per creative.
                   items:
                     type: object
                     required: [locale, headline, body, description]
@@ -41135,6 +42414,8 @@ paths:
                     Deprecated: send it inside `platformSpecificData` instead (Meta today; TikTok's nested shape is planned). The flat field keeps working during the deprecation window; sending both shapes returns a 400.
 
                     Meta bid strategy applied to the ad set.
+
+                    OpenAI Ads: required on every ad group via this flat field, the only channel it supports (`platformSpecificData` is Meta/LinkedIn-only and returns 400 for OpenAI). No auto-bid option exists; send `LOWEST_COST_WITH_BID_CAP` or `COST_CAP` together with `bidAmount`, omitting it returns 400.
                 bidAmount:
                   type: number
                   deprecated: true
@@ -41261,6 +42542,21 @@ paths:
                     Ads (`POST /v1/ads/boost`) always use `TT_USER` regardless
                     of this field — TikTok requires the original organic
                     post's author identity for Spark.
+                smartPlus:
+                  type: boolean
+                  description: |
+                    TikTok only. Creates the ad as a TikTok Upgraded Smart+
+                    campaign: TikTok automates targeting, bidding and delivery. Supports goals
+                    `conversions` (Smart+ Web Conversions), `lead_generation` (Smart+ Lead
+                    Generation with a website form on `linkUrl`; TikTok Instant Forms not supported)
+                    and `app_promotion` (Smart+ App installs; the ad's destination is the app store,
+                    so `linkUrl` is not used). The web goals require `promotedObject.pixelId` AND
+                    `promotedObject.customEventType`; `app_promotion` requires
+                    `promotedObject.applicationId` instead.
+                    Targeting works like on any TikTok ad (defaults to `countries: ["US"]` when
+                    omitted); TikTok automates delivery within it.
+                    The budget lives on the Smart+ campaign (Campaign Budget Optimization); a `lifetime`
+                    budget additionally requires `endDate`. Cannot be combined with `adSetId`.
                 promotedObject:
                   type: object
                   description: |
@@ -41276,12 +42572,15 @@ paths:
 
                     Other Meta goals (engagement, traffic, awareness, video_views) ignore this field.
 
-                    **TikTok**: only `goal: conversions` uses it.
+                    **TikTok**: used by `goal: conversions` and the Smart+ goals (`smartPlus: true`).
                       - `pixelId` maps to the ad group's `pixel_id`. Required: a TikTok website-conversion
                         ad group without a pixel is rejected with `40002: Please select a pixel`.
                       - `customEventType` maps to the ad group's `optimization_event` (the pixel event to
-                        optimise for). Optional: TikTok accepts a pixel-only auto-bid conversion ad group.
+                        optimise for). Optional on the regular conversions flow, required on Smart+.
                         See the `customEventType` field below for the valid TikTok codes.
+                      - `applicationId` (Smart+ `goal: app_promotion` only) maps to the ad group's `app_id`:
+                        the App ID of an app registered on the TikTok Ads account (Assets → Events →
+                        App Events). Install optimization needs the app's MMP tracking configured.
 
                     The remaining `promotedObject.*` fields are Meta-only. Platforms other than
                     Meta and TikTok ignore `promotedObject` entirely.
@@ -41290,6 +42589,9 @@ paths:
                       type: string
                       description: |
                         Pixel ID. **Meta:** Facebook Pixel ID, required for `goal: conversions`.
+                        Requires `customEventType` alongside it; Meta rejects any promoted_object
+                        carrying `pixel_id` without `custom_event_type` (error_subcode 1885014),
+                        even when `customConversionId` is also present.
                         **TikTok:** TikTok Pixel ID, required for `goal: conversions`.
                         To discover the pixels an ad account can use, call
                         `GET /v1/accounts/{accountId}/tracking-tags?adAccountId=act_...` (each entry
@@ -41339,7 +42641,12 @@ paths:
                       description: "App Store / Play Store listing URL. Required for `goal: app_promotion`."
                     customConversionId:
                       type: string
-                      description: Custom Conversion ID, when optimising against one instead of a standard event.
+                      description: |
+                        Custom Conversion ID, when optimising against one instead of a standard
+                        event. Accepted alone by this API, without `pixelId` or `customEventType`.
+                        If `pixelId` is also sent, `customEventType` is still required on the
+                        promoted_object (Meta rejects `pixel_id` without `custom_event_type`,
+                        error_subcode 1885014).
                     productCatalogId:
                       type: string
                       description: Catalog ID for catalog/Advantage+ Shopping campaigns.
@@ -41398,6 +42705,16 @@ paths:
           description: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.
         '422':
           description: Platform ads connection required (TikTok Ads, X Ads) or missing linked account
+        '502':
+          description: |
+            The platform rejected the request, or failed to produce media the ad
+            needs (e.g. Meta generated no poster for an uploaded video when no
+            `video.thumbnailUrl` was supplied). Inspect `platformError` for the
+            upstream payload. Failures we raise carry a `reason`; a payload
+            forwarded verbatim from Meta may not. On the `creatives[]` shape a
+            missing poster also carries `creativeIndex` and `videoUrl` to
+            identify the entry. An upstream 4xx status is forwarded instead
+            of 502.
 
   /v1/ads/leads:
     get:
@@ -41438,16 +42755,16 @@ paths:
                       type: object
                       properties:
                         id: { type: string, description: Zernio lead id. }
-                        leadgenId: { type: string, description: Meta lead id. }
+                        leadgenId: { type: string, description: 'Meta lead id. On LinkedIn, the leadFormResponse id.' }
                         formId: { type: string }
                         formName: { type: [string, "null"] }
                         accountId: { type: string }
                         adId: { type: [string, "null"] }
                         adsetId: { type: [string, "null"] }
-                        campaignId: { type: [string, "null"] }
+                        campaignId: { type: [string, "null"], description: 'On LinkedIn, this is the LinkedIn Campaign id, which corresponds to platformAdSetId on GET /v1/ads (LinkedIn''s Campaign Group is Zernio''s campaign).' }
                         isOrganic: { type: boolean }
                         createdTime: { type: [string, "null"], description: ISO 8601. }
-                        fields: { type: object, additionalProperties: { type: string }, description: "Question key → answer." }
+                        fields: { type: object, additionalProperties: { type: string }, description: 'Question key → answer. On LinkedIn, the key is the lowercased predefinedField, else the question name, else the numeric questionId; multiple-choice values are option labels (unlike Meta, which returns the option key).' }
                         fieldData: { type: array, items: { type: object }, description: "Raw Meta field_data." }
                   pagination:
                     type: object
@@ -41803,6 +43120,7 @@ paths:
         '400': { description: "Invalid input, or Meta rejected the image" }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '501': { description: Only supported on Meta (facebook/instagram) }
+        '502': { description: "Meta accepted the request then failed to produce the media (upload session, chunk transfer, processing timeout, or a response with no image hash). Inspect `platformError.reason`." }
 
     get:
       x-resource-group: "ads"
@@ -41906,6 +43224,28 @@ paths:
         markets, and every id is usable in `regions`/`cities`/`metros` keys on
         `POST /v1/ads/create`.
 
+        LinkedIn geo searches also return every matching level in one list, and
+        neither `geoType` nor `countryCode` is applied: LinkedIn's typeahead only
+        returns a name and a URN per result, with no level or country field to
+        filter on. Every result has `type` set to `location`, and its id is a
+        `urn:li:geo:*` URN usable as a `regions[].key` on `POST /v1/ads/create`,
+        `POST /v1/ads/boost` and `POST /v1/ads/targeting/reach-estimate`.
+
+        Pinterest resolves against three whole-catalog endpoints (interests, locations,
+        regions) with no server-side query or pagination, so matching, ranking and the
+        `limit` cutoff all happen in Zernio; the catalog is independent of any ad account
+        and results never carry `audienceSize`. Names come back localized to the connected
+        Pinterest account's language (there is no way to force a locale), so match against
+        whatever language that account returns. `geoType` routes to a different catalog:
+        `country` and `metro_area` read the locations catalog (`type` is `country` or
+        `metro`); `region` reads the regions catalog (`type` is `region`, its id a
+        `regions[].key` on `POST /v1/ads/create`); `all` and the default `city` merge both
+        catalogs with honest per-entry `type`s, since Pinterest has no city-level catalog
+        and `city` is an alias for `all`, not a literal city search. `zip`, `subcity`,
+        `neighborhood`, `place` and `geo_market` return a 400: Pinterest exposes no
+        postal-code catalog, pass postal codes directly as `targeting.zips: [{ key }]` on
+        `POST /v1/ads/create`.
+
         For geo queries, `q` should contain only the locality name (e.g. `"Amsterdam"`,
         not `"Amsterdam, NL"`). Use `countryCode` to disambiguate.
       security:
@@ -41914,7 +43254,7 @@ paths:
         - { name: accountId, in: query, required: true, schema: { type: string }, description: "Social account ID (a connected account on the target ad platform)." }
         - { name: q, in: query, required: true, schema: { type: string }, description: "Search query. For geo, the locality name only (no region/country suffix)." }
         - { name: dimension, in: query, required: false, schema: { type: string, enum: [geo, interest, behavior, income], default: interest }, description: "What to search. `geo` resolves locations (scope further with `geoType`), `interest`/`behavior` resolve audience entities, `income` resolves income-tier options. Defaults to `interest` for backward compatibility with the deprecated /v1/ads/interests alias." }
-        - { name: geoType, in: query, required: false, schema: { type: string, enum: [country, region, city, zip, metro], default: city }, description: "Only used when `dimension=geo`. The kind of location to resolve. Defaults to `city`." }
+        - { name: geoType, in: query, required: false, schema: { type: string, enum: [all, country, region, city, subcity, neighborhood, place, zip, metro_area, geo_market], default: city }, description: "Only used when `dimension=geo`. The kind of location to resolve. `all` searches every type in one relevance-ranked call. Defaults to `city`." }
         - { name: countryCode, in: query, required: false, schema: { type: string, minLength: 2, maxLength: 2 }, description: "ISO 3166-1 alpha-2 country code (e.g. NL) to scope a geo search." }
         - { name: limit, in: query, required: false, schema: { type: integer, minimum: 1, maximum: 100, default: 25 }, description: "Maximum results to return." }
       responses:
@@ -41933,7 +43273,7 @@ paths:
                       properties:
                         id: { type: string, description: "The platform's opaque id. Use as a geo `key` (regions/cities/zips/metros) or an entity `id` (interests/behaviors) in TargetingSpec." }
                         name: { type: string, description: "Human-readable label." }
-                        type: { type: string, description: "What the result is (e.g. city, region, country, zip, metro, interest, behavior, income)." }
+                        type: { type: string, description: "What the result is (e.g. city, region, country, zip, metro, location, interest, behavior, income)." }
                         path: { type: array, items: { type: string }, description: "Optional breadcrumb of parent labels (e.g. ['United States', 'California', 'Los Angeles']). Disambiguates same-named results." }
                         audienceSize: { type: [integer, "null"], description: "Optional estimated reachable users for this option, when the platform returns it." }
         '400':
@@ -43788,6 +45128,7 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { description: Account not found }
         '422': { description: "No Facebook Page resolved for the account" }
+        '502': { description: "Meta accepted the request then failed to produce the media (upload session, chunk transfer, processing timeout, or a response with no image hash). Inspect `platformError.reason`." }
 
   /v1/ads/call:
     post:
@@ -43827,6 +45168,7 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '404': { description: Account not found }
         '422': { description: "No Facebook Page resolved for the account" }
+        '502': { description: "Meta accepted the request then failed to produce the media (upload session, chunk transfer, processing timeout, or a response with no image hash). Inspect `platformError.reason`." }
 
   /v1/ads/ctwa:
     post:
@@ -44018,6 +45360,7 @@ paths:
         '403': { description: 'Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).' }
         '404': { description: Account not found or not accessible. }
         '405': { description: Platform does not support listing tracking tags. }
+        '502': { description: 'Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Retryable.' }
 
     post:
       x-resource-group: "ads"
@@ -44083,6 +45426,7 @@ paths:
         '404': { description: Account not found or not accessible. }
         '405': { description: Platform does not support creating tracking tags. }
         '422': { description: 'OpenAI Ads only: the ad account is not enabled for pixel management. Contact your OpenAI partner representative.' }
+        '502': { description: 'Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Creating a pixel is NOT idempotent, so before retrying confirm with GET /v1/accounts/{accountId}/tracking-tags that no pixel was created.' }
 
   /v1/accounts/{accountId}/tracking-tags/{tagId}:
     get:
@@ -44116,6 +45460,7 @@ paths:
         '403': { description: 'Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).' }
         '404': { description: Account or tracking tag not found. }
         '405': { description: Platform does not support fetching a tracking tag. }
+        '502': { description: 'Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Retryable.' }
 
     patch:
       x-resource-group: "ads"
@@ -44182,6 +45527,7 @@ paths:
         '403': { description: 'Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).' }
         '404': { description: Account or tracking tag not found. }
         '405': { description: Platform does not support updating tracking tags. }
+        '502': { description: 'Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Retryable.' }
 
   /v1/accounts/{accountId}/tracking-tags/{tagId}/shared-accounts:
     get:
@@ -44212,6 +45558,7 @@ paths:
         '403': { description: 'Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).' }
         '404': { description: Account or tracking tag not found. }
         '405': { description: Platform does not support shared accounts. }
+        '502': { description: 'Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Retryable.' }
 
     post:
       x-resource-group: "ads"
@@ -44254,6 +45601,7 @@ paths:
         '403': { description: 'Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).' }
         '404': { description: Account or tracking tag not found. }
         '405': { description: Platform does not support shared accounts. }
+        '502': { description: 'Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Retryable.' }
 
     delete:
       x-resource-group: "ads"
@@ -44278,6 +45626,7 @@ paths:
         '403': { description: 'Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).' }
         '404': { description: Account or tracking tag not found. }
         '405': { description: Platform does not support shared accounts. }
+        '502': { description: 'Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Retryable.' }
 
   /v1/accounts/{accountId}/tracking-tags/{tagId}/stats:
     get:
@@ -44345,6 +45694,448 @@ paths:
         '403': { description: 'Ads access required (Ads add-on on legacy plans, included on usage-based plans), or the Meta token lacks ads permissions (reconnect required).' }
         '404': { description: Account or tracking tag not found. }
         '405': { description: Platform does not support tracking-tag stats. }
+        '502': { description: 'Meta was unreachable or returned an unclassified error (type: platform_error; the raw Meta payload is in platformError). Retryable.' }
+
+  /v1/accounts/{accountId}/blogs:
+    get:
+      x-resource-group: "publishing"
+      operationId: listBlogs
+      tags: ["Blogs"]
+      x-platforms: ["shopify"]
+      summary: List blogs
+      description: |
+        Lists the blogs on the connected store, newest-first as the platform
+        returns them. Cursor-paginated: pass `limit` (1-50, default 20) and the
+        `cursor` from a previous response's `nextCursor`; `nextCursor` is null
+        when there are no more pages.
+
+        Supported on Shopify (platform `shopify`). Accounts on platforms
+        without blogs support return 400; a blogs-capable platform that lacks
+        this specific operation returns 405.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string }, description: 'Connected Shopify SocialAccount id.' }
+        - { name: limit, in: query, required: false, schema: { type: integer, minimum: 1, maximum: 50, default: 20 }, description: 'Page size (1-50).' }
+        - { name: cursor, in: query, required: false, schema: { type: string }, description: 'Opaque cursor from a previous response. Omit for the first page.' }
+      responses:
+        '200':
+          description: Blogs listed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  platform: { type: string, enum: [shopify] }
+                  blogs:
+                    type: array
+                    items: { $ref: '#/components/schemas/Blog' }
+                  nextCursor: { type: [string, "null"], description: 'Cursor for the next page; null when there are no more pages.' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { description: 'The platform rejected the request (code insufficient_permissions); reconnect the Shopify account to restore access.' }
+        '404': { description: 'Account not found or not accessible (code account_not_found).' }
+        '405': { description: Platform does not support listing blogs. }
+        '429': { description: 'Rate limited, either by Zernio or by Shopify. Retry later.' }
+
+    post:
+      x-resource-group: "publishing"
+      operationId: createBlog
+      tags: ["Blogs"]
+      x-platforms: ["shopify"]
+      summary: Create a blog
+      description: |
+        Creates a blog on the connected store. The platform generates the URL
+        `handle` from the title when omitted.
+
+        Supported on Shopify (platform `shopify`). Accounts on platforms
+        without blogs support return 400; a blogs-capable platform that lacks
+        this specific operation returns 405.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string }, description: 'Connected Shopify SocialAccount id.' }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [title]
+              properties:
+                title: { type: string, minLength: 1 }
+                handle: { type: string, minLength: 1, description: 'URL slug. Generated from the title when omitted.' }
+      responses:
+        '201':
+          description: Blog created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  platform: { type: string, enum: [shopify] }
+                  blog: { $ref: '#/components/schemas/Blog' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { description: 'The platform rejected the request (code insufficient_permissions); reconnect the Shopify account to restore access.' }
+        '404': { description: 'Account not found or not accessible (code account_not_found).' }
+        '405': { description: Platform does not support creating blogs. }
+        '429': { description: 'Rate limited, either by Zernio or by Shopify. Retry later.' }
+
+  /v1/accounts/{accountId}/blogs/{blogId}:
+    get:
+      x-resource-group: "publishing"
+      operationId: getBlog
+      tags: ["Blogs"]
+      x-platforms: ["shopify"]
+      summary: Get a blog
+      description: |
+        Fetches a single blog. `blogId` is the platform's numeric blog id from
+        `GET /v1/accounts/{accountId}/blogs`, not a Zernio id.
+
+        Supported on Shopify (platform `shopify`). Accounts on platforms
+        without blogs support return 400; a blogs-capable platform that lacks
+        this specific operation returns 405.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string }, description: 'Connected Shopify SocialAccount id.' }
+        - { name: blogId, in: path, required: true, schema: { type: string, pattern: '^\d+$' }, description: 'Platform-native numeric blog id. Non-numeric values return 400.' }
+      responses:
+        '200':
+          description: Blog fetched
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  platform: { type: string, enum: [shopify] }
+                  blog: { $ref: '#/components/schemas/Blog' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { description: 'The platform rejected the request (code insufficient_permissions); reconnect the Shopify account to restore access.' }
+        '404': { description: 'Account not found or not accessible (code account_not_found), or blog not found (code blog_not_found).' }
+        '405': { description: Platform does not support fetching a blog. }
+        '429': { description: 'Rate limited, either by Zernio or by Shopify. Retry later.' }
+
+    patch:
+      x-resource-group: "publishing"
+      operationId: updateBlog
+      tags: ["Blogs"]
+      x-platforms: ["shopify"]
+      summary: Update a blog
+      description: |
+        Partial-updates a blog. Send any subset of `title` and `handle`; at
+        least one field is required (an empty body returns 400).
+
+        Supported on Shopify (platform `shopify`). Accounts on platforms
+        without blogs support return 400; a blogs-capable platform that lacks
+        this specific operation returns 405.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string }, description: 'Connected Shopify SocialAccount id.' }
+        - { name: blogId, in: path, required: true, schema: { type: string, pattern: '^\d+$' }, description: 'Platform-native numeric blog id. Non-numeric values return 400.' }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              description: 'At least one field is required.'
+              properties:
+                title: { type: string, minLength: 1 }
+                handle: { type: string, minLength: 1, description: 'URL slug. Changing it changes the blog URL on the store.' }
+      responses:
+        '200':
+          description: Blog updated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  platform: { type: string, enum: [shopify] }
+                  blog: { $ref: '#/components/schemas/Blog' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { description: 'The platform rejected the request (code insufficient_permissions); reconnect the Shopify account to restore access.' }
+        '404': { description: 'Account not found or not accessible (code account_not_found), or blog not found (code blog_not_found).' }
+        '405': { description: Platform does not support updating a blog. }
+        '429': { description: 'Rate limited, either by Zernio or by Shopify. Retry later.' }
+
+    delete:
+      x-resource-group: "publishing"
+      operationId: deleteBlog
+      tags: ["Blogs"]
+      x-platforms: ["shopify"]
+      summary: Delete a blog
+      description: |
+        Deletes the blog AND every article in it. The delete happens on the
+        platform and is permanent; Zernio stores nothing to restore it from.
+
+        Supported on Shopify (platform `shopify`). Accounts on platforms
+        without blogs support return 400; a blogs-capable platform that lacks
+        this specific operation returns 405.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string }, description: 'Connected Shopify SocialAccount id.' }
+        - { name: blogId, in: path, required: true, schema: { type: string, pattern: '^\d+$' }, description: 'Platform-native numeric blog id. Non-numeric values return 400.' }
+      responses:
+        '204': { description: Blog deleted (no content). }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { description: 'The platform rejected the request (code insufficient_permissions); reconnect the Shopify account to restore access.' }
+        '404': { description: 'Account not found or not accessible (code account_not_found), or blog not found (code blog_not_found).' }
+        '405': { description: Platform does not support deleting a blog. }
+        '429': { description: 'Rate limited, either by Zernio or by Shopify. Retry later.' }
+
+  /v1/accounts/{accountId}/blogs/{blogId}/articles:
+    get:
+      x-resource-group: "publishing"
+      operationId: listBlogArticles
+      tags: ["Blogs"]
+      x-platforms: ["shopify"]
+      summary: List blog articles
+      description: |
+        Lists the articles of a blog. Cursor-paginated: pass `limit` (1-50,
+        default 20) and the `cursor` from a previous response's `nextCursor`;
+        `nextCursor` is null when there are no more pages.
+
+        Supported on Shopify (platform `shopify`). Accounts on platforms
+        without blogs support return 400; a blogs-capable platform that lacks
+        this specific operation returns 405.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string }, description: 'Connected Shopify SocialAccount id.' }
+        - { name: blogId, in: path, required: true, schema: { type: string, pattern: '^\d+$' }, description: 'Platform-native numeric blog id. Non-numeric values return 400.' }
+        - { name: limit, in: query, required: false, schema: { type: integer, minimum: 1, maximum: 50, default: 20 }, description: 'Page size (1-50).' }
+        - { name: cursor, in: query, required: false, schema: { type: string }, description: 'Opaque cursor from a previous response. Omit for the first page.' }
+      responses:
+        '200':
+          description: Articles listed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  platform: { type: string, enum: [shopify] }
+                  articles:
+                    type: array
+                    items: { $ref: '#/components/schemas/BlogArticle' }
+                  nextCursor: { type: [string, "null"], description: 'Cursor for the next page; null when there are no more pages.' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { description: 'The platform rejected the request (code insufficient_permissions); reconnect the Shopify account to restore access.' }
+        '404': { description: 'Account not found or not accessible (code account_not_found), or blog not found (code blog_not_found).' }
+        '405': { description: Platform does not support listing articles. }
+        '429': { description: 'Rate limited, either by Zernio or by Shopify. Retry later.' }
+
+    post:
+      x-resource-group: "publishing"
+      operationId: createBlogArticle
+      tags: ["Blogs"]
+      x-platforms: ["shopify"]
+      summary: Create a blog article
+      description: |
+        Creates an article on the blog. Publishing behavior:
+
+        - `isPublished: false` keeps the article as a draft.
+        - A future `publishDate` schedules publication natively on the
+          platform; the platform publishes it at that time with no Zernio
+          queue involved.
+        - `seo.title` / `seo.description` map to Shopify's global `title_tag`
+          and `description_tag` metafields (the fields Shopify themes read for
+          the page title and meta description).
+
+        Supported on Shopify (platform `shopify`). Accounts on platforms
+        without blogs support return 400; a blogs-capable platform that lacks
+        this specific operation returns 405.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string }, description: 'Connected Shopify SocialAccount id.' }
+        - { name: blogId, in: path, required: true, schema: { type: string, pattern: '^\d+$' }, description: 'Platform-native numeric blog id. Non-numeric values return 400.' }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [title]
+              properties:
+                title: { type: string, minLength: 1 }
+                bodyHtml: { type: string, description: 'Article body as HTML.' }
+                handle: { type: string, description: 'URL slug. Generated from the title when omitted.' }
+                tags: { type: array, items: { type: string } }
+                author: { type: string, description: 'Display name of the article author.' }
+                excerpt: { type: string, description: 'Short summary shown in blog listings.' }
+                image:
+                  type: object
+                  required: [url]
+                  description: 'Featured image. The platform downloads it, so the URL must be publicly reachable.'
+                  properties:
+                    url: { type: string, format: uri }
+                    altText: { type: string }
+                seo:
+                  type: object
+                  description: 'Search-engine overrides. Maps to Shopify global metafields (title_tag and description_tag).'
+                  properties:
+                    title: { type: string }
+                    description: { type: string }
+                isPublished: { type: boolean, description: 'Set false to create the article as a draft.' }
+                publishDate: { type: string, format: date-time, description: 'ISO 8601 datetime with offset (or Z). A future date schedules publication natively on the platform.' }
+      responses:
+        '201':
+          description: Article created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  platform: { type: string, enum: [shopify] }
+                  article: { $ref: '#/components/schemas/BlogArticle' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { description: 'The platform rejected the request (code insufficient_permissions); reconnect the Shopify account to restore access.' }
+        '404': { description: 'Account not found or not accessible (code account_not_found), or blog not found (code blog_not_found).' }
+        '405': { description: Platform does not support creating articles. }
+        '429': { description: 'Rate limited, either by Zernio or by Shopify. Retry later.' }
+
+  /v1/accounts/{accountId}/blogs/{blogId}/articles/{articleId}:
+    get:
+      x-resource-group: "publishing"
+      operationId: getBlogArticle
+      tags: ["Blogs"]
+      x-platforms: ["shopify"]
+      summary: Get a blog article
+      description: |
+        Fetches a single article. An article addressed through a blog it does
+        not belong to is a 404 (code blog_article_not_found).
+
+        Supported on Shopify (platform `shopify`). Accounts on platforms
+        without blogs support return 400; a blogs-capable platform that lacks
+        this specific operation returns 405.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string }, description: 'Connected Shopify SocialAccount id.' }
+        - { name: blogId, in: path, required: true, schema: { type: string, pattern: '^\d+$' }, description: 'Platform-native numeric blog id. Non-numeric values return 400.' }
+        - { name: articleId, in: path, required: true, schema: { type: string, pattern: '^\d+$' }, description: 'Platform-native numeric article id. Non-numeric values return 400.' }
+      responses:
+        '200':
+          description: Article fetched
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  platform: { type: string, enum: [shopify] }
+                  article: { $ref: '#/components/schemas/BlogArticle' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { description: 'The platform rejected the request (code insufficient_permissions); reconnect the Shopify account to restore access.' }
+        '404': { description: 'Account not found or not accessible (code account_not_found), blog not found (code blog_not_found), or article not found (code blog_article_not_found).' }
+        '405': { description: Platform does not support fetching an article. }
+        '429': { description: 'Rate limited, either by Zernio or by Shopify. Retry later.' }
+
+    patch:
+      x-resource-group: "publishing"
+      operationId: updateBlogArticle
+      tags: ["Blogs"]
+      x-platforms: ["shopify"]
+      summary: Update a blog article
+      description: |
+        Partial-updates an article. Send any subset of the create fields
+        (`title`, `bodyHtml`, `handle`, `tags`, `author`, `excerpt`, `image`,
+        `seo`, `isPublished`, `publishDate`); at least one field is required
+        (an empty body returns 400). `isPublished` and `publishDate` behave as
+        on create: `isPublished: false` unpublishes back to a draft and a
+        future `publishDate` schedules publication natively on the platform.
+
+        Supported on Shopify (platform `shopify`). Accounts on platforms
+        without blogs support return 400; a blogs-capable platform that lacks
+        this specific operation returns 405.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string }, description: 'Connected Shopify SocialAccount id.' }
+        - { name: blogId, in: path, required: true, schema: { type: string, pattern: '^\d+$' }, description: 'Platform-native numeric blog id. Non-numeric values return 400.' }
+        - { name: articleId, in: path, required: true, schema: { type: string, pattern: '^\d+$' }, description: 'Platform-native numeric article id. Non-numeric values return 400.' }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              description: 'At least one field is required.'
+              properties:
+                title: { type: string, minLength: 1 }
+                bodyHtml: { type: string, description: 'Article body as HTML.' }
+                handle: { type: string, description: 'URL slug of the article.' }
+                tags: { type: array, items: { type: string }, description: 'Replaces the full tag list.' }
+                author: { type: string, description: 'Display name of the article author.' }
+                excerpt: { type: string, description: 'Short summary shown in blog listings.' }
+                image:
+                  type: object
+                  required: [url]
+                  description: 'Featured image. The platform downloads it, so the URL must be publicly reachable.'
+                  properties:
+                    url: { type: string, format: uri }
+                    altText: { type: string }
+                seo:
+                  type: object
+                  description: 'Search-engine overrides. Maps to Shopify global metafields (title_tag and description_tag).'
+                  properties:
+                    title: { type: string }
+                    description: { type: string }
+                isPublished: { type: boolean, description: 'Set false to unpublish the article back to a draft.' }
+                publishDate: { type: string, format: date-time, description: 'ISO 8601 datetime with offset (or Z). A future date schedules publication natively on the platform.' }
+      responses:
+        '200':
+          description: Article updated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  platform: { type: string, enum: [shopify] }
+                  article: { $ref: '#/components/schemas/BlogArticle' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { description: 'The platform rejected the request (code insufficient_permissions); reconnect the Shopify account to restore access.' }
+        '404': { description: 'Account not found or not accessible (code account_not_found), blog not found (code blog_not_found), or article not found (code blog_article_not_found).' }
+        '405': { description: Platform does not support updating an article. }
+        '429': { description: 'Rate limited, either by Zernio or by Shopify. Retry later.' }
+
+    delete:
+      x-resource-group: "publishing"
+      operationId: deleteBlogArticle
+      tags: ["Blogs"]
+      x-platforms: ["shopify"]
+      summary: Delete a blog article
+      description: |
+        Deletes the article. The delete happens on the platform and is
+        permanent; Zernio stores nothing to restore it from.
+
+        Supported on Shopify (platform `shopify`). Accounts on platforms
+        without blogs support return 400; a blogs-capable platform that lacks
+        this specific operation returns 405.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: path, required: true, schema: { type: string }, description: 'Connected Shopify SocialAccount id.' }
+        - { name: blogId, in: path, required: true, schema: { type: string, pattern: '^\d+$' }, description: 'Platform-native numeric blog id. Non-numeric values return 400.' }
+        - { name: articleId, in: path, required: true, schema: { type: string, pattern: '^\d+$' }, description: 'Platform-native numeric article id. Non-numeric values return 400.' }
+      responses:
+        '204': { description: Article deleted (no content). }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { description: 'The platform rejected the request (code insufficient_permissions); reconnect the Shopify account to restore access.' }
+        '404': { description: 'Account not found or not accessible (code account_not_found), blog not found (code blog_not_found), or article not found (code blog_article_not_found).' }
+        '405': { description: Platform does not support deleting an article. }
+        '429': { description: 'Rate limited, either by Zernio or by Shopify. Retry later.' }
 
   /v1/verify/verifications:
     post: