late-sdk 0.0.544 → 0.0.545

data/openapi.yaml

@@ -3791,6 +3791,22 @@ components:
         timestamp:
           type: string
           format: date-time
+    DiscordGuildMember:
+      type: object
+      description: A Discord guild member, returned verbatim from Discord's API.
+      properties:
+        user:
+          type: object
+          properties:
+            id: { type: string, description: User snowflake }
+            username: { type: string }
+            discriminator: { type: string }
+            avatar: { type: [string, "null"] }
+            global_name: { type: [string, "null"], description: "User's display name (post-2023 Discord rebrand)" }
+        nick: { type: [string, "null"], description: Guild-specific nickname }
+        roles: { type: array, items: { type: string }, description: Snowflake IDs of roles assigned to this member }
+        joined_at: { type: string, format: date-time }
+        premium_since: { type: [string, "null"], format: date-time, description: When the user started boosting the server }
     DiscordRole:
       type: object
       description: A Discord guild role, returned verbatim from Discord's API.
@@ -20002,10 +20018,10 @@ paths:
         to all members joined in the last 7 days") on the actual platform shape.
 
         **Important:** this endpoint requires the privileged "Server Members
-        Intent" enabled on the Discord app (Developer Portal → Bot tab → toggle
-        "Server Members Intent" ON, then Save). Without it, Discord returns an
-        empty array with no error. Verify the intent is enabled before relying
-        on this endpoint.
+        Intent" on the Discord application. If the intent is not enabled,
+        Discord rejects the call and this endpoint returns **403**. Single
+        member lookup and prefix search (see the sibling endpoints) do not
+        need the intent.
 
         Pagination: pass `after` = the last `user.id` from the previous page.
         Omit on the first call. Response includes a `nextCursor` and `hasMore`
@@ -20025,21 +20041,7 @@ paths:
                 properties:
                   data:
                     type: array
-                    items:
-                      type: object
-                      properties:
-                        user:
-                          type: object
-                          properties:
-                            id: { type: string, description: User snowflake }
-                            username: { type: string }
-                            discriminator: { type: string }
-                            avatar: { type: [string, "null"] }
-                            global_name: { type: [string, "null"], description: User's display name (post-2023 Discord rebrand) }
-                        nick: { type: [string, "null"], description: Guild-specific nickname }
-                        roles: { type: array, items: { type: string }, description: Snowflake IDs of roles assigned to this member }
-                        joined_at: { type: string, format: date-time }
-                        premium_since: { type: [string, "null"], format: date-time, description: When the user started boosting the server }
+                    items: { $ref: '#/components/schemas/DiscordGuildMember' }
                   pagination:
                     type: object
                     properties:
@@ -20047,8 +20049,67 @@ paths:
                       hasMore: { type: boolean }
         '400': { description: Invalid query params. }
         '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { description: The Server Members Intent is not enabled on the Discord application. }
         '404': { description: Discord account not found or not in this guild. }
 
+  /v1/discord/guilds/{guildId}/members/search:
+    get:
+      operationId: searchDiscordGuildMembers
+      tags: [Discord]
+      summary: Search Discord guild members
+      description: |
+        Search guild members whose username or nickname **starts with** the
+        query (Discord matches prefixes only, not substrings).
+
+        Does not require the privileged Server Members Intent, so this works
+        even where the full member listing returns 403.
+      parameters:
+        - { name: guildId, in: path, required: true, schema: { type: string } }
+        - { name: accountId, in: query, required: true, schema: { type: string } }
+        - { name: query, in: query, required: true, schema: { type: string, minLength: 1, maxLength: 100 }, description: Username or nickname prefix to match. }
+        - { name: limit, in: query, required: false, schema: { type: integer, minimum: 1, maximum: 1000, default: 25 } }
+      responses:
+        '200':
+          description: Matching guild members.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: '#/components/schemas/DiscordGuildMember' }
+        '400': { description: Invalid query params. }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { description: Discord account not found or not in this guild. }
+
+  /v1/discord/guilds/{guildId}/members/{userId}:
+    get:
+      operationId: getDiscordGuildMember
+      tags: [Discord]
+      summary: Get a Discord guild member
+      description: |
+        Fetch a single guild member by Discord user id.
+
+        Does not require the privileged Server Members Intent, so this works
+        even where the full member listing returns 403.
+      parameters:
+        - { name: guildId, in: path, required: true, schema: { type: string } }
+        - { name: userId, in: path, required: true, schema: { type: string }, description: Discord user snowflake. }
+        - { name: accountId, in: query, required: true, schema: { type: string } }
+      responses:
+        '200':
+          description: The guild member.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data: { $ref: '#/components/schemas/DiscordGuildMember' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { description: 'Discord account not found, or the user is not a member of this guild.' }
+
   /v1/discord/guilds/{guildId}/members/{userId}/roles/{roleId}:
     put:
       operationId: addDiscordMemberRole
@@ -25956,6 +26017,155 @@ 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
@@ -33046,6 +33256,55 @@ paths:
         '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:
       operationId: updateAdCampaignStatus
@@ -33333,6 +33592,98 @@ 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
@@ -34655,6 +35006,302 @@ paths:
         '401': { $ref: '#/components/responses/Unauthorized' }
         '501': { description: Only supported on Meta (facebook/instagram) }
 
+  /v1/ads/businesses:
+    get:
+      operationId: listMetaBusinesses
+      tags: [Ads]
+      summary: Businesses list (Meta)
+      description: |-
+        Business Manager portfolios the connected Meta user belongs to (Meta's `/me/businesses`),
+        rows returned verbatim (id, name, verification_status, created_time). Token-scoped, so no
+        `adAccountId` is needed. Meta only; for TikTok Business Centers use
+        `GET /v1/ads/business-centers`.
+      security:
+        - bearerAuth: []
+      parameters:
+        - { name: accountId, in: query, required: true, schema: { type: string }, description: "Zernio SocialAccount id (posting or ads variant) used to resolve the Meta token." }
+        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 25 }, description: Rows per page }
+        - { name: after, in: query, schema: { type: string }, description: "Cursor from paging.after of the previous page." }
+      responses:
+        '200':
+          description: Businesses (raw Meta shape)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items: { type: object, description: "Raw Meta business row (id, name, verification_status, created_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/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)." }
+                creativeFeatures:
+                  type: object
+                  additionalProperties: { type: string, enum: [OPT_IN, OPT_OUT] }
+                  description: 'Advantage+ creative enhancements: partial map of Meta creative feature keys (snake_case) to enroll status, forwarded as degrees_of_freedom_spec.creative_features_spec. Unspecified features default to OPT_OUT.'
+      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
@@ -35172,6 +35819,13 @@ paths:
                 billingEvent: { type: string, description: "Meta only. Explicit ad-set `billing_event`. Defaults to `IMPRESSIONS`. Forwarded verbatim to Meta, which validates compatibility with the optimization goal." }
                 buyingType: { type: string, enum: [AUCTION, RESERVED], description: "Meta only. RESERVED = Reach & Frequency: requires `rfPredictionId` (a RESERVED prediction from /v1/ads/rf-predictions + /reserve). Budget, schedule and pricing come from the reservation, so budgetAmount/budgetType are not required and bid fields are ignored. Only the plain single-ad shape (no creatives[], adSetId, existingCampaignId or dynamicCreative)." }
                 rfPredictionId: { type: string, description: "Meta only. The RESERVED prediction id the R&F ad set runs on (reserving mints a new id — pass that one). Requires buyingType RESERVED." }
+                creativeFeatures:
+                  type: object
+                  additionalProperties: { type: string, enum: [OPT_IN, OPT_OUT] }
+                  description: 'Meta only. Advantage+ creative enhancements: a partial map of Meta creative feature keys (snake_case, e.g. enhance_cta, image_brightness_and_contrast, text_optimizations) to enroll status, forwarded as degrees_of_freedom_spec.creative_features_spec. Meta validates the keys; unspecified features default to OPT_OUT. The legacy standard_enhancements bundle is deprecated by Meta and rejected.'
+                validateOnly:
+                  type: boolean
+                  description: 'Meta only, single standalone shape only (no creatives[], adSetId, or RESERVED). Dry-run: each node runs Meta''s execution_options validate_only and NOTHING is created or persisted. Children need real parents, so a fresh tree validates the campaign + creative (the ad set needs its campaign to exist — pass existingCampaignId to validate it too; the ad itself is never validatable pre-create). A Meta validation failure returns the 400 verbatim; success returns 200 with per-node results instead of an ad.'
                 budgetAmount: { type: number, description: "Required on legacy + multi-creative shapes. Inherited on attach." }
                 budgetType: { type: string, enum: [daily, lifetime], description: "Required on legacy + multi-creative shapes. Inherited on attach." }
                 status:
@@ -35801,6 +36455,23 @@ paths:
                       type: string
                       description: Product Set ID inside the catalog.
       responses:
+        '200':
+          description: 'validateOnly dry-run passed — nothing was created'
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  validateOnly: { type: boolean, enum: [true] }
+                  results:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        node: { type: string, enum: [campaign, adSet, creative, ad] }
+                        status: { type: string, enum: [validated, skipped] }
+                        reason: { type: string, description: "Why the node could not be validated (only on skipped)." }
+                  message: { type: string }
         '201':
           description: Ad(s) created
           content:
@@ -35822,7 +36493,7 @@ paths:
                       platformAdSetId: { type: string }
                       message: { type: string }
         '400':
-          description: Missing required fields, invalid values, or non-Meta platform used with creatives[] / adSetId
+          description: 'Missing required fields, invalid values, non-Meta platform used with creatives[] / adSetId, or a Meta validateOnly validation failure (verbatim)'
         '401': { $ref: '#/components/responses/Unauthorized' }
         '403':
           description: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans.
@@ -36102,6 +36773,43 @@ paths:
         '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:
       operationId: searchAdInterests
@@ -36672,12 +37380,15 @@ paths:
     put:
       operationId: updateAdAudience
       tags: [Ad Audiences]
-      summary: Update saved targeting audience
+      summary: Update an audience
       description: |
-        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.
+        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.
       security:
         - bearerAuth: []
       parameters:
@@ -36706,13 +37417,15 @@ paths:
                   audience: { type: object }
                   message: { type: string }
         '400':
-          description: Invalid body (no fields provided or malformed spec)
+          description: 'Invalid body (no fields provided, malformed spec, or spec on a platform audience)'
         '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 is not saved_targeting (uploaded/derived audiences are managed on the platform)
+          description: The audience has no platform counterpart to update
+        '501':
+          description: Platform audience updates are only supported on Meta
     delete:
       operationId: deleteAdAudience
       tags: [Ad Audiences]