zernio-sdk 0.0.539 → 0.0.541

data/openapi.yaml

@@ -2664,7 +2664,13 @@ components:
                 description: Attachment type (image, video, file, sticker, audio)
               url:
                 type: string
-                description: Attachment URL (may expire for Meta platforms)
+                description: |
+                  Where to fetch the attachment. The contract depends on direction and
+                  platform: inbound WhatsApp media points at the authenticated
+                  `GET /v1/whatsapp/media/{mediaId}` and requires
+                  `Authorization: Bearer <your API key>`, while outgoing media carries the
+                  URL originally supplied and Instagram / Facebook / Telegram carry direct
+                  platform CDN links that need no authentication.
               payload:
                 type: object
                 description: Additional attachment metadata
@@ -2878,7 +2884,19 @@ components:
                     description: Attachment type (image, video, file, sticker, audio)
                   url:
                     type: string
-                    description: Attachment URL (may expire for Meta platforms)
+                    description: |
+                      Where to fetch the attachment. **The contract differs by platform.**
+
+                      - **WhatsApp**: points at `GET /v1/whatsapp/media/{mediaId}`, an
+                        authenticated Zernio endpoint. You MUST send
+                        `Authorization: Bearer <your API key>`; fetching it without that
+                        header returns `401`. Download and store the bytes when this
+                        webhook arrives: Meta drops inbound media after a limited
+                        retention window, after which the endpoint answers `400`
+                        permanently and the media is unrecoverable.
+                      - **Instagram / Facebook / Telegram**: a direct platform CDN link
+                        that needs no authentication and expires on the platform's own
+                        schedule.
                   payload:
                     type: object
                     description: Additional attachment metadata
@@ -3190,7 +3208,13 @@ components:
                     description: Attachment type (image, video, file, sticker, audio)
                   url:
                     type: string
-                    description: Attachment URL (may expire for Meta platforms)
+                    description: |
+                      Where to fetch the attachment. For outgoing messages this is the
+                      media URL as sent, so for WhatsApp it is the URL you supplied when
+                      publishing (WhatsApp sends media by link), not a Zernio endpoint,
+                      and it needs no Zernio credentials. Contrast the inbound direction:
+                      `message.received` attachment URLs on WhatsApp point at the
+                      authenticated `GET /v1/whatsapp/media/{mediaId}`.
                   payload:
                     type: object
                     description: Additional attachment metadata
@@ -9255,7 +9279,9 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ErrorResponse'
+                type: object
+                properties:
+                  error: { type: string }
               examples:
                 invalidMetric:
                   value:
@@ -11182,20 +11208,10 @@ paths:
                 key: "temp/1234567890_abc123_my-video.mp4"
                 expiresIn: 3600
         '400':
-          description: Invalid request (missing filename, contentType, or unsupported content type)
+          description: 'Invalid request (missing filename, unsupported contentType, or size out of range)'
           content:
             application/json:
-              schema:
-                type: object
-                properties:
-                  error: { type: string }
-              examples:
-                missing_filename:
-                  value: { error: "Missing required fields: filename and contentType" }
-                invalid_type:
-                  value: { error: "Content type not allowed: text/plain" }
-                file_too_large:
-                  value: { error: "File too large. Maximum size is 5GB." }
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
         '401': { $ref: '#/components/responses/Unauthorized' }
   /v1/reddit/search:
     get:
@@ -22574,6 +22590,49 @@ paths:
         '403':
           description: Inbox addon required
 
+  /v1/whatsapp/media/{mediaId}:
+    get:
+      operationId: getWhatsAppMedia
+      tags: [Inbox]
+      summary: Download WhatsApp media
+      description: |
+        Streams the binary for a WhatsApp attachment. This is the endpoint the
+        `url` on a WhatsApp `attachments[]` entry points at, in both the
+        `message.received` webhook and the List messages response.
+
+        **This is an authenticated endpoint, not a public link.** Send
+        `Authorization: Bearer <your API key>` exactly as you would for any other
+        call. Passing the URL straight to a browser, an LLM vision API, or a
+        no-code "download file" step without the header returns `401`. This is
+        the most common integration mistake on this endpoint, and it differs from
+        Instagram, Facebook and Telegram, whose `attachments[].url` is a direct
+        CDN link that needs no header.
+
+        **Fetch on receipt, not lazily.** WhatsApp media lives in Meta's media
+        store, not ours, and it is removed after a limited retention window
+        (currently 7 days, and Meta has been dropping some inbound media sooner).
+        Once Meta drops it the media is unrecoverable and this endpoint answers
+        `400` permanently, so retrying will never succeed. Download and store the
+        bytes when the webhook arrives.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: mediaId, in: path, required: true, schema: { type: string }, description: 'The media id from `attachments[].payload.id`.' }
+        - { name: accountId, in: query, required: true, schema: { type: string }, description: 'The WhatsApp account that received the media.' }
+      responses:
+        '200':
+          description: The media binary, streamed with its original content type.
+          content:
+            application/octet-stream:
+              schema: { type: string, format: binary }
+        '400':
+          description: 'Media is no longer available on WhatsApp servers (expired or deleted by Meta). Permanent, do not retry.'
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404':
+          description: 'Account not found, not accessible to the caller, or the media does not belong to it.'
+        '502':
+          description: Meta could not be reached or returned an unexpected error.
+
   /v1/inbox/conversations/{conversationId}/messages/{messageId}:
     patch:
       operationId: editInboxMessage
@@ -25737,19 +25796,13 @@ paths:
       summary: Send an SMS/MMS
       description: |
         Sends an SMS (or MMS when `mediaUrls` is set) from one of your
-        SMS-enabled numbers, or from an approved alphanumeric sender ID
-        (`/v1/sms/sender-ids`). At least one of `text` / `mediaUrls` is
-        required. Numbers are normalized to E.164, so `from` matches regardless
-        of formatting and replies thread into the same inbox conversation.
+        SMS-enabled numbers. At least one of `text` / `mediaUrls` is required.
+        Both numbers are normalized to E.164, so `from` matches regardless of
+        formatting and replies thread into the same inbox conversation.
 
         US numbers must have an approved carrier registration
         (`/v1/sms/registrations`) before messages deliver.
 
-        **Alphanumeric sender IDs** are one-way and international only: they
-        cannot reach the US, Canada, or Puerto Rico (403), are text-only (no
-        MMS), and recipients cannot reply. Some destination countries
-        substitute a numeric sender to ensure delivery.
-
         **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
@@ -25773,7 +25826,7 @@ paths:
               type: object
               required: [from, to]
               properties:
-                from: { type: string, description: 'One of your SMS-enabled numbers (E.164; formatting is normalized), or an approved alphanumeric sender ID (3-11 letters/digits/spaces, created via `/v1/sms/sender-ids`).' }
+                from: { type: string, description: One of your SMS-enabled numbers (E.164; formatting is normalized). }
                 to: { type: string, description: Recipient number (E.164). }
                 text: { type: string, description: "Message body. Required unless `mediaUrls` is set. Max 10 SMS segments (1530 GSM-7 or 670 unicode characters)." }
                 mediaUrls:
@@ -25796,13 +25849,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' }
-        '403': { description: 'Send refused by a gate: US registration missing/pending, MMS not supported by this sender, or an alphanumeric sender ID addressed to the US, Canada or Puerto Rico.' }
-        '404': { description: "No SMS-enabled number or sender ID matches `from`" }
+        '404': { description: "No SMS-enabled number matches `from`" }
         '409': { description: Same Idempotency-Key still processing; retry after a short backoff }
         '422': { description: Idempotency-Key reused with a different body }
-        '429': { description: 'Daily sender ID message limit reached for the workspace (alphanumeric sends only, code `alpha_daily_limit_reached`; resets midnight UTC, raisable via support).' }
         '502': { description: Carrier-side send failed }
 
   /v1/sms/lookup:
@@ -25872,155 +25922,6 @@ paths:
               schema: { type: string, description: "`format=csv` download. Columns: phone_number, opted_out_at, keyword, our_number" }
         '401': { $ref: '#/components/responses/Unauthorized' }
 
-  /v1/sms/sender-ids:
-    post:
-      operationId: createSmsSenderId
-      tags: [SMS]
-      summary: Create an alphanumeric sender ID
-      description: |
-        Registers an alphanumeric sender ID (e.g. `ZERNIO`) — a branded `from`
-        for one-way international SMS. No phone number purchase or carrier
-        registration is needed; once created, pass it as `from` on
-        `POST /v1/sms/messages`.
-
-        Constraints: 3-11 characters (letters, digits, spaces; at least one
-        letter). Sends cannot reach the US, Canada, or Puerto Rico, are
-        text-only, and recipients cannot reply. Sender IDs that impersonate
-        well-known brands or institutions are rejected, and an ID already
-        registered by another workspace returns 409 (active sender IDs are
-        globally unique, first-come-first-served). Creating the same sender ID
-        again is a no-op (re-activates it after a delete).
-      security:
-        - bearerAuth: []
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required: [senderId]
-              properties:
-                senderId:
-                  type: string
-                  minLength: 3
-                  maxLength: 11
-                  description: 'The sender ID recipients will see (3-11 letters/digits/spaces, at least one letter, no leading/trailing space).'
-      responses:
-        '200':
-          description: Sender ID created (or re-activated).
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  id: { type: string, description: Sender ID resource id. }
-                  senderId: { type: string }
-                  isActive: { type: boolean }
-        '400': { $ref: '#/components/responses/BadRequest' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '403': { description: 'Workspace is not on usage-based billing, or already holds the maximum of 5 active sender IDs (code `sender_id_limit_reached`; raisable via support).' }
-        '409': { description: 'Sender ID already registered by another workspace (code `sender_id_taken`).' }
-        '422': { description: 'Sender ID rejected: it appears to impersonate a protected brand or institution.' }
-    get:
-      operationId: listSmsSenderIds
-      tags: [SMS]
-      summary: List alphanumeric sender IDs
-      security:
-        - bearerAuth: []
-      responses:
-        '200':
-          description: The workspace's sender IDs, newest first.
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  senderIds:
-                    type: array
-                    items:
-                      type: object
-                      properties:
-                        id: { type: string }
-                        senderId: { type: string }
-                        isActive: { type: boolean }
-                        createdAt: { type: [string, "null"], format: date-time }
-                  budget:
-                    type: object
-                    description: 'Workspace-wide daily sending budget, shared by every sender ID (resets midnight UTC).'
-                    properties:
-                      cap: { type: integer, description: 'Daily message cap (raisable via `/v1/sms/sender-ids/limit-request`).' }
-                      usedToday: { type: integer, description: Messages already counted against today's cap. }
-                      level: { type: integer, description: 'Cap tier (Level 1 = 500/day).' }
-                      pendingRequest:
-                        type: [object, "null"]
-                        description: 'The in-flight cap-raise request awaiting review, or null. While set, further requests return 409.'
-                        properties:
-                          requestedCap: { type: integer }
-                          level: { type: integer }
-                          requestedAt: { type: [string, "null"], format: date-time }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-
-  /v1/sms/sender-ids/limit-request:
-    post:
-      operationId: requestSmsSenderIdLimitIncrease
-      tags: [SMS]
-      summary: Request a higher sender ID daily limit
-      description: |
-        Asks support to raise the workspace's daily sender-ID message cap.
-        There is no self-serve raise: the request (desired cap + use case) is
-        reviewed manually, usually within a business day.
-      security:
-        - bearerAuth: []
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required: [requestedCap, reason]
-              properties:
-                requestedCap: { type: integer, description: 'Desired daily message cap. Must exceed the current cap.' }
-                reason: { type: string, minLength: 10, maxLength: 2000, description: 'Use case and audience (what you send, to whom, opt-in status).' }
-      responses:
-        '200':
-          description: Request submitted for review.
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  requested: { type: boolean }
-                  requestedCap: { type: integer }
-        '400': { $ref: '#/components/responses/BadRequest' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '409': { description: 'A cap-raise request is already awaiting review (code `sender_id_raise_pending`); one at a time.' }
-        '503': { description: Request could not be submitted; retry or contact support. }
-
-  /v1/sms/sender-ids/{id}:
-    delete:
-      operationId: deleteSmsSenderId
-      tags: [SMS]
-      summary: Delete an alphanumeric sender ID
-      description: |
-        Deactivates the sender ID so it can no longer send. Re-creating the
-        same sender ID via `POST /v1/sms/sender-ids` re-activates it.
-      security:
-        - bearerAuth: []
-      parameters:
-        - { name: id, in: path, required: true, schema: { type: string }, description: Sender ID resource id. }
-      responses:
-        '200':
-          description: Sender ID deactivated.
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  deleted: { type: boolean }
-        '400': { $ref: '#/components/responses/BadRequest' }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '404': { description: Sender ID not found. }
-
   /v1/sms/registrations:
     post:
       operationId: startSmsRegistration
@@ -33109,54 +33010,6 @@ 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.
-    post:
-      operationId: createAdCampaign
-      tags: [Ad Campaigns]
-      summary: Create a standalone campaign (Meta)
-      description: |-
-        Creates a campaign WITHOUT its first ad set / ad (the ODAX shell only). Ad sets join it
-        later via `existingCampaignId` on the create endpoints. A budget here is campaign-level
-        (CBO) by definition; omit it for ABO (each ad set carries its own budget). Created
-        `PAUSED` unless `status: ACTIVE`. The campaign materializes in `/v1/ads/tree` via the
-        next sync discovery pass. Meta only.
-      security:
-        - bearerAuth: []
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required: [accountId, adAccountId, name, goal]
-              properties:
-                accountId: { type: string, description: "Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token." }
-                adAccountId: { type: string, description: "Meta ad account id (act_<n>)." }
-                name: { type: string, maxLength: 255 }
-                goal:
-                  type: string
-                  enum: [engagement, traffic, awareness, video_views, lead_generation, lead_conversion, job_applicants, conversions, app_promotion, catalog_sales]
-                  description: Mapped to the ODAX objective (same mapping as POST /v1/ads/create).
-                specialAdCategories:
-                  type: array
-                  items: { type: string, enum: [HOUSING, EMPLOYMENT, CREDIT, ISSUES_ELECTIONS_POLITICS, FINANCIAL_PRODUCTS_SERVICES, ONLINE_GAMBLING_AND_GAMING] }
-                budgetAmount: { type: number, description: "Campaign-level (CBO) budget in whole currency units. Requires budgetType." }
-                budgetType: { type: string, enum: [daily, lifetime] }
-                status: { type: string, enum: [ACTIVE, PAUSED], default: PAUSED }
-      responses:
-        '201':
-          description: Campaign created
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  adAccountId: { type: string }
-                  campaignId: { type: string, description: Platform id of the new campaign }
-                  objective: { type: string, description: "Resolved ODAX objective (e.g. OUTCOME_SALES)." }
-                  status: { type: string, enum: [ACTIVE, PAUSED] }
-        '400': { description: "Invalid input, or Meta rejected the create" }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '501': { description: Only supported on Meta (facebook/instagram) }
 
   /v1/ads/campaigns/{campaignId}/status:
     put:
@@ -33445,98 +33298,6 @@ paths:
         '404': { description: Source campaign not found }
         '501': { description: Operation not supported on this platform }
 
-  /v1/ads/ad-sets/{adSetId}/duplicate:
-    post:
-      operationId: duplicateAdSet
-      tags: [Ad Campaigns]
-      summary: Duplicate an ad set (Meta)
-      description: |-
-        Duplicates an ad set, including its ads and creatives by default (`deepCopy: true`),
-        via Meta's native `POST /{adset-id}/copies`. The copy is created paused so callers can
-        review before launching. `campaignId` retargets the copy into another campaign; omitted
-        = the source's own campaign. The new hierarchy materializes asynchronously — sync
-        discovery is triggered automatically (`syncAfter: false` to skip). Meta only.
-      security:
-        - bearerAuth: []
-      parameters:
-        - { name: adSetId, in: path, required: true, schema: { type: string }, description: Source platform ad set ID }
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required: [platform]
-              properties:
-                platform: { type: string, enum: [facebook, instagram] }
-                campaignId: { type: string, description: Destination platform campaign id (defaults to the source's campaign) }
-                deepCopy: { type: boolean, default: true, description: Copy child ads + creatives }
-                statusOption: { type: string, enum: [ACTIVE, PAUSED, INHERITED_FROM_SOURCE], default: PAUSED }
-                startTime: { type: string, format: date-time, description: Reschedule the copy's start time }
-                endTime: { type: string, format: date-time }
-                renameStrategy: { type: string, enum: [DEEP_RENAME, ONLY_TOP_LEVEL_RENAME, NO_RENAME] }
-                renamePrefix: { type: string }
-                renameSuffix: { type: string }
-                syncAfter: { type: boolean, default: true }
-      responses:
-        '200':
-          description: Ad set duplicated
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  copiedAdSetId: { type: string, description: Platform ID of the new ad set }
-                  discovery: { type: string, enum: [triggered, skipped, failed] }
-                  raw: { type: object, description: Meta's native copy response (includes ad_object_ids for child copies) }
-        '400': { description: Invalid input }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '404': { description: Source ad set not found }
-        '501': { description: Only supported on Meta (facebook/instagram) }
-
-  /v1/ads/{adId}/duplicate:
-    post:
-      operationId: duplicateAd
-      tags: [Ads]
-      summary: Duplicate an ad (Meta)
-      description: |-
-        Duplicates a single ad via Meta's native `POST /{ad-id}/copies`. The copy is created
-        paused. `adSetId` retargets the copy into another ad set; omitted = the source's own ad
-        set. Accepts the Zernio ad id or the platform ad id. Sync discovery is triggered
-        automatically (`syncAfter: false` to skip). Meta only.
-      security:
-        - bearerAuth: []
-      parameters:
-        - { name: adId, in: path, required: true, schema: { type: string }, description: Zernio ad ID or platform ad ID }
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                adSetId: { type: string, description: Destination platform ad set id (defaults to the source's ad set) }
-                statusOption: { type: string, enum: [ACTIVE, PAUSED, INHERITED_FROM_SOURCE], default: PAUSED }
-                renameStrategy: { type: string, enum: [DEEP_RENAME, ONLY_TOP_LEVEL_RENAME, NO_RENAME] }
-                renamePrefix: { type: string }
-                renameSuffix: { type: string }
-                syncAfter: { type: boolean, default: true }
-      responses:
-        '200':
-          description: Ad duplicated
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  copiedAdId: { type: string, description: Platform ID of the new ad }
-                  discovery: { type: string, enum: [triggered, skipped, failed] }
-                  raw: { type: object }
-        '400': { description: Invalid input }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '404': { description: Ad not found }
-        '501': { description: Only supported on Meta (facebook/instagram) }
-
   /v1/ads/ad-sets/{adSetId}:
     get:
       operationId: getAdSetDetails
@@ -34859,263 +34620,6 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '501': { description: Only supported on Meta (facebook/instagram) }
 
-  /v1/ads/labels:
-    get:
-      operationId: listAdLabels
-      tags: [Ads]
-      summary: Ad labels (Meta)
-      description: |-
-        Lists the ad account's organizational labels (Meta's `/act_X/adlabels`), rows returned
-        verbatim (id, name, created/updated time). Meta only.
-      security:
-        - bearerAuth: []
-      parameters:
-        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token." }
-        - { name: adAccountId, in: query, required: true, schema: { type: string }, description: "Meta ad account id (act_<n>)." }
-        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 25 }, description: Rows per page }
-        - { name: after, in: query, schema: { type: string }, description: "Cursor from paging.after of the previous page." }
-      responses:
-        '200':
-          description: Ad labels (raw Meta shape)
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  adAccountId: { type: string }
-                  data:
-                    type: array
-                    items: { type: object, description: "Raw Meta ad label row (id, name, created_time, updated_time)." }
-                  paging:
-                    type: object
-                    properties:
-                      after: { type: [string, "null"], description: "Cursor for the next page; null when exhausted." }
-        '400': { description: "Invalid input, or Meta rejected the query" }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '501': { description: Only supported on Meta (facebook/instagram) }
-
-  /v1/ads/high-demand-periods:
-    get:
-      operationId: listHighDemandPeriods
-      tags: [Ads]
-      summary: High demand periods / budget schedules (Meta)
-      description: |-
-        Scheduled budget increases (Meta's budget-scheduling API). The Graph edge lives on the
-        campaign and ad-set nodes only, so exactly one of `campaignId` / `adSetId` (platform
-        ids) is required. Rows returned verbatim (budget_value, budget_value_type, time window,
-        recurrence). Meta only.
-      security:
-        - bearerAuth: []
-      parameters:
-        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token." }
-        - { name: campaignId, in: query, schema: { type: string }, description: "Platform campaign id. Exactly one of campaignId / adSetId." }
-        - { name: adSetId, in: query, schema: { type: string }, description: "Platform ad set id. Exactly one of campaignId / adSetId." }
-        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 25 }, description: Rows per page }
-        - { name: after, in: query, schema: { type: string }, description: "Cursor from paging.after of the previous page." }
-      responses:
-        '200':
-          description: Budget schedules (raw Meta shape)
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  objectId: { type: string, description: "The campaign / ad set id the schedules belong to." }
-                  data:
-                    type: array
-                    items: { type: object, description: "Raw Meta high-demand-period row." }
-                  paging:
-                    type: object
-                    properties:
-                      after: { type: [string, "null"], description: "Cursor for the next page; null when exhausted." }
-        '400': { description: "Invalid input, or Meta rejected the query" }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '501': { description: Only supported on Meta (facebook/instagram) }
-
-  /v1/ads/creatives:
-    get:
-      operationId: listAdCreatives
-      tags: [Ads]
-      summary: Creative library (Meta)
-      description: |-
-        Lists the ad account's creative library (Meta's `/act_X/adcreatives`), rows returned
-        verbatim. The default projection covers id, name, status, object type, thumbnail,
-        object_story_spec / asset_feed_spec and url_tags; `fields` is a raw-passthrough
-        override. Any creative id here is reusable on the create endpoints via
-        `existingCreativeId`. Meta only.
-      security:
-        - bearerAuth: []
-      parameters:
-        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token." }
-        - { name: adAccountId, in: query, required: true, schema: { type: string }, description: "Meta ad account id (act_<n>)." }
-        - { name: fields, in: query, schema: { type: string }, description: "Comma-separated Graph field override (supports nested {} projections)." }
-        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 25 }, description: Rows per page }
-        - { name: after, in: query, schema: { type: string }, description: "Cursor from paging.after of the previous page." }
-      responses:
-        '200':
-          description: Creatives (raw Meta shape)
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  adAccountId: { type: string }
-                  data:
-                    type: array
-                    items: { type: object, description: "Raw Meta creative row." }
-                  paging:
-                    type: object
-                    properties:
-                      after: { type: [string, "null"], description: "Cursor for the next page; null when exhausted." }
-        '400': { description: "Invalid input, or Meta rejected the query" }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '501': { description: Only supported on Meta (facebook/instagram) }
-    post:
-      operationId: createAdCreative
-      tags: [Ads]
-      summary: Create a standalone creative (Meta)
-      description: |-
-        Creates a creative in the library WITHOUT an ad, reusable on the create endpoints via
-        `existingCreativeId`. Provide exactly one of `imageUrl` (uploaded server-side),
-        `imageHash` (from POST /v1/ads/images or the library list), or `carouselCards` (2-10
-        hand-built cards). The Page (and linked Instagram account, when present) is resolved
-        from `accountId` as the story actor. Meta only.
-      security:
-        - bearerAuth: []
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required: [accountId, adAccountId, headline, body, linkUrl]
-              properties:
-                accountId: { type: string, description: "Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token and Page." }
-                adAccountId: { type: string, description: "Meta ad account id (act_<n>)." }
-                headline: { type: string, maxLength: 255 }
-                body: { type: string, description: Primary text }
-                description: { type: string, maxLength: 255, description: "Link description below the headline; omitted = Meta scrapes the destination's OG description." }
-                callToAction: { type: string, default: LEARN_MORE, description: "CTA type (same whitelist as POST /v1/ads/create)." }
-                linkUrl: { type: string, format: uri }
-                imageUrl: { type: string, format: uri, description: "Publicly reachable image; uploaded to the account's library server-side." }
-                imageHash: { type: string, description: "Existing library image hash (POST /v1/ads/images or GET /v1/ads/images)." }
-                carouselCards:
-                  type: array
-                  minItems: 2
-                  maxItems: 10
-                  items:
-                    type: object
-                    required: [imageUrl, linkUrl]
-                    properties:
-                      imageUrl: { type: string, format: uri }
-                      linkUrl: { type: string, format: uri }
-                      headline: { type: string, maxLength: 255 }
-                      description: { type: string, maxLength: 255 }
-                      callToAction: { type: string }
-                urlTags: { type: string, description: "Appended to every outbound URL (e.g. utm_source=fb)." }
-      responses:
-        '201':
-          description: Creative created
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  adAccountId: { type: string }
-                  creativeId: { type: string, description: "Platform creative id, reusable via existingCreativeId." }
-        '400': { description: "Invalid input, or Meta rejected the create" }
-        '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) }
-
-  /v1/ads/creatives/{creativeId}:
-    get:
-      operationId: getAdCreative
-      tags: [Ads]
-      summary: Creative details (Meta)
-      description: |-
-        One creative's details, verbatim from Meta. `fields` is a raw-passthrough override of
-        the default projection. Meta only.
-      security:
-        - bearerAuth: []
-      parameters:
-        - { name: creativeId, in: path, required: true, schema: { type: string }, description: Platform creative id }
-        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token." }
-        - { name: fields, in: query, schema: { type: string }, description: "Comma-separated Graph field override (supports nested {} projections)." }
-      responses:
-        '200':
-          description: Creative details
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  creative: { type: object, description: Raw Meta creative node }
-        '400': { description: "Invalid input, or Meta rejected the query" }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '501': { description: Only supported on Meta (facebook/instagram) }
-    put:
-      operationId: updateAdCreative
-      tags: [Ads]
-      summary: Rename a creative (Meta)
-      description: |-
-        Renames a creative. Creatives are immutable on Meta beyond `name` — for content changes
-        create a new creative (POST /v1/ads/creatives) and swap it onto the ad
-        (PUT /v1/ads/{adId} with `creative`). Meta only.
-      security:
-        - bearerAuth: []
-      parameters:
-        - { name: creativeId, in: path, required: true, schema: { type: string }, description: Platform creative id }
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required: [accountId, name]
-              properties:
-                accountId: { type: string, description: "Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token." }
-                name: { type: string, maxLength: 255 }
-      responses:
-        '200':
-          description: Creative renamed
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  creativeId: { type: string }
-                  name: { type: string }
-                  message: { type: string }
-        '400': { description: "Invalid input, or Meta rejected the update" }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '501': { description: Only supported on Meta (facebook/instagram) }
-    delete:
-      operationId: deleteAdCreative
-      tags: [Ads]
-      summary: Delete a creative (Meta)
-      description: |-
-        Deletes a creative from the library. Meta only allows deleting creatives not referenced
-        by any ad — otherwise its 400 surfaces verbatim.
-      security:
-        - bearerAuth: []
-      parameters:
-        - { name: creativeId, in: path, required: true, schema: { type: string }, description: Platform creative id }
-        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token." }
-      responses:
-        '200':
-          description: Creative deleted
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  creativeId: { type: string }
-                  message: { type: string }
-        '400': { description: "Invalid input, the creative is in use, or Meta rejected the delete" }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '501': { description: Only supported on Meta (facebook/instagram) }
-
   /v1/ads/accounts/finance:
     get:
       operationId: getAdAccountFinance
@@ -36562,42 +36066,6 @@ paths:
         '400': { description: "Invalid input, or Meta rejected the image" }
         '401': { $ref: '#/components/responses/Unauthorized' }
         '501': { description: Only supported on Meta (facebook/instagram) }
-    get:
-      operationId: listAdImages
-      tags: [Ads]
-      summary: Ad image library (Meta)
-      description: |-
-        Lists the ad account's image library (Meta's `/act_X/adimages`), rows returned verbatim.
-        The default projection covers hash, url, name, dimensions and status; `fields` is a
-        raw-passthrough override. Any `hash` here is reusable wherever Meta accepts
-        `image_hash` (e.g. `imageHash` on POST /v1/ads/creatives). Meta only.
-      security:
-        - bearerAuth: []
-      parameters:
-        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token." }
-        - { name: adAccountId, in: query, required: true, schema: { type: string }, description: "Meta ad account id (act_<n>)." }
-        - { name: fields, in: query, schema: { type: string }, description: "Comma-separated Graph field override (supports nested {} projections)." }
-        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 25 }, description: Rows per page }
-        - { name: after, in: query, schema: { type: string }, description: "Cursor from paging.after of the previous page." }
-      responses:
-        '200':
-          description: Ad images (raw Meta shape)
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  adAccountId: { type: string }
-                  data:
-                    type: array
-                    items: { type: object, description: "Raw Meta ad image row (hash, url, name, width, height, status)." }
-                  paging:
-                    type: object
-                    properties:
-                      after: { type: [string, "null"], description: "Cursor for the next page; null when exhausted." }
-        '400': { description: "Invalid input, or Meta rejected the query" }
-        '401': { $ref: '#/components/responses/Unauthorized' }
-        '501': { description: Only supported on Meta (facebook/instagram) }
 
   /v1/ads/interests:
     get:
@@ -37169,15 +36637,12 @@ paths:
     put:
       operationId: updateAdAudience
       tags: [Ad Audiences]
-      summary: Update an audience
+      summary: Update saved targeting audience
       description: |
-        Update an audience. `saved_targeting` audiences accept `name`, `description`, and `spec`
-        (full replacement, no merge, Zernio-only, no platform call). Platform audiences
-        (uploaded/website/lookalike) accept `name` and `description` only, updated on the
-        platform first and then mirrored locally; their rules are immutable, so `spec` returns
-        400 for them. Platform audience updates are Meta-only for now (other platforms return
-        501). Ads already created from a saved_targeting audience are unaffected, they snapshot
-        the targeting at creation.
+        Update a `saved_targeting` audience's name, description, or spec. Only `saved_targeting` audiences are
+        updatable (they exist only on Zernio); uploaded/derived audiences return 422, delete and recreate those
+        instead. `spec` replaces the stored spec wholesale (no merge). Ads already created from this audience are
+        unaffected, they snapshot the targeting at creation.
       security:
         - bearerAuth: []
       parameters:
@@ -37206,15 +36671,13 @@ paths:
                   audience: { type: object }
                   message: { type: string }
         '400':
-          description: 'Invalid body (no fields provided, malformed spec, or spec on a platform audience)'
+          description: Invalid body (no fields provided or malformed spec)
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403':
           description: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.
         '404': { $ref: '#/components/responses/NotFound' }
         '422':
-          description: The audience has no platform counterpart to update
-        '501':
-          description: Platform audience updates are only supported on Meta
+          description: The audience is not saved_targeting (uploaded/derived audiences are managed on the platform)
     delete:
       operationId: deleteAdAudience
       tags: [Ad Audiences]