@giveitsmaller/contracts 0.55.0 → 0.58.0

package/openapi/api.yaml

@@ -89,7 +89,7 @@ info:
     of truth instead of hardcoding magic numbers. A runtime
     `GET /api/uploads/limits` endpoint for dynamic discovery
     (per-tier / per-environment overrides) is a deferred follow-up.
-  version: 2.162.0
+  version: 2.171.0
   contact:
     name: API Support
 
@@ -221,18 +221,38 @@ paths:
                     required_tier: "enterprise"
         '413':
           description: |
-            File exceeds the absolute maximum upload size (across all
-            tiers). For tier-specific size caps below this absolute
-            limit, the server returns 403 with
-            `error_type: tier_restriction, restriction_kind: file_size`
-            instead.
+            The upload is too large. Two rejection cases, discriminated by the
+            `ErrorEnvelope.error` code:
+
+            - **Byte size** — the file exceeds the absolute maximum upload size
+              (across all tiers). For tier-specific size caps below this
+              absolute limit, the server returns 403 with `error_type:
+              tier_restriction, restriction_kind: file_size` instead.
+            - **Pixel dimensions** (`error: IMAGE_DIMENSIONS_TOO_LARGE`) — a
+              decodable raster image whose `width × height` exceeds the
+              configured pixel ceiling (`UPLOAD_MAX_IMAGE_PIXELS`, default
+              16 MP). The server reads dimensions from the file **header** (no
+              full-bitmap decode) and rejects **before** decoding, so a
+              within-byte-limit but huge-dimension image (e.g. a few-KB 26 MP
+              PNG that would decode to ~100 MB) is rejected up front rather than
+              exhausting memory. Non-decoded raster types (TIFF/BMP/ICO) and
+              non-images are unaffected.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
-              example:
-                success: false
-                error: "File size exceeds maximum allowed (100 GiB)"
+              examples:
+                file_too_large:
+                  summary: File exceeds the absolute maximum byte size
+                  value:
+                    success: false
+                    error: "File size exceeds maximum allowed (100 GiB)"
+                image_dimensions_too_large:
+                  summary: Decodable raster exceeds the pixel-dimension ceiling
+                  value:
+                    success: false
+                    error: "IMAGE_DIMENSIONS_TOO_LARGE"
+                    message: "Image dimensions exceed the maximum allowed (16 MP)."
         '415':
           description: |
             Unsupported file type at the contract level (no tier permits
@@ -1567,6 +1587,49 @@ paths:
                     success: false
                     error: "BAD_REQUEST"
                     message: "Invalid workflow request"
+        '401':
+          description: |
+            An authentication credential was **presented** on this endpoint's
+            mixed auth surface (`security: [{}, bearerAuth, sessionAuth]`) but
+            was rejected. `error_type` (an `AuthErrorType`) discriminates:
+
+            - `reauthentication_required` — a **session** credential was
+              present but is stale (expired / revoked / owner no longer
+              resolves). The endpoint **fails closed** rather than silently
+              creating an anonymous, null-owner workflow (apxXxptO); the caller
+              *was* authenticated and must re-authenticate. Clients branch on
+              this value to surface a re-auth prompt and retry, preserving
+              in-progress work.
+            - Bearer-path failures — an `Authorization: Bearer <key>` credential
+              rejected by `ApiKeyAuthenticator` before the controller ran:
+              `api_key_invalid` (key not found / revoked / owner missing), or
+              `authentication_required` (the authenticator's fallback for an
+              otherwise-unmodelled auth failure).
+
+            A genuinely **anonymous** request (no credential at all) is NOT a
+            `401` — it is accepted and creates an anonymous workflow. The
+            `error_type` is narrowed to exactly these three codes (an `allOf`
+            over `AuthErrorResponse`): the login-only `invalid_credentials` and
+            the four `account_*` codes (which are `403` outcomes) are excluded,
+            so the contract advertises only what this endpoint can actually emit
+            at `401`.
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/AuthErrorResponse'
+                  - type: object
+                    properties:
+                      error_type:
+                        enum:
+                          - reauthentication_required
+                          - api_key_invalid
+                          - authentication_required
+              example:
+                success: false
+                error: "REAUTHENTICATION_REQUIRED"
+                error_type: "reauthentication_required"
+                message: "Your session has expired. Please sign in again."
         '403':
           description: |
             Forbidden — tier-quota or feature-tier restriction. Discriminated
@@ -2765,12 +2828,16 @@ paths:
         via that cookie.
 
         Failure responses distinguish between:
-          - `401 invalid_credentials` — wrong password OR correct password on an
-            unverified account (collapsed for anti-enumeration).
-          - `403 account_locked|account_disabled|account_deleted|account_deletion_expired`
-            — persisted account-state failures.
+          - `401 invalid_credentials` — wrong password, correct password on an
+            unverified account, OR any persisted account-status failure
+            (locked / disabled / deleted / deletion-expired). **All collapsed
+            into a single `401 invalid_credentials`** so the login response
+            never reveals whether an account exists or what state it is in
+            (anti-enumeration; Mc6wiUzc). The `account_*` `error_type`s are
+            NOT emitted on login — they survive only on the API-key path and
+            the live-session enforcer (see `AuthErrorType`).
           - `429` — infrastructure rate-limit (too many attempts in the current
-            window). Distinct from `account_locked`, which is persisted state.
+            window); carries no `error_type`.
       operationId: loginUser
       security: []  # anonymous (entry point — you're logging in, no creds yet)
       tags:
@@ -2862,61 +2929,41 @@ paths:
                 error: "Request body is invalid."
         '401':
           description: |
-            Invalid credentials, or correct password on an unverified account
-            (collapsed into `invalid_credentials` for anti-enumeration). The
-            `error` field carries the human-readable message; consumers must
-            not assume a particular phrasing across releases.
+            Authentication failed — **always `invalid_credentials`**. Covers
+            wrong password, correct password on an unverified account, AND any
+            persisted account-status failure (locked / disabled / deleted /
+            deletion-expired), all deliberately collapsed into one value so the
+            response never reveals account existence or state (anti-enumeration;
+            Mc6wiUzc). The `error` field carries a human-readable message;
+            consumers must not assume a particular phrasing across releases.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/AuthErrorResponse'
+                # error_type is CONSTRAINED to `invalid_credentials` (not the
+                # full AuthErrorType enum) so the anti-enumeration collapse is
+                # CONTRACT-ENFORCED, not just prose — login can never emit an
+                # `account_*` value (Mc6wiUzc).
+                allOf:
+                  - $ref: '#/components/schemas/AuthErrorResponse'
+                  - type: object
+                    required:
+                      - error_type
+                    properties:
+                      error_type:
+                        type: string
+                        enum:
+                          - invalid_credentials
               example:
                 success: false
                 error: "Invalid credentials."
                 error_type: "invalid_credentials"
-        '403':
-          description: |
-            Account-status failure — `error_type` is one of `account_locked`,
-            `account_disabled`, `account_deleted`, or `account_deletion_expired`.
-            These reflect persisted account state, not infrastructure throttling
-            (for that see 429).
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/AuthErrorResponse'
-              examples:
-                accountLocked:
-                  summary: Account is in a persisted locked state
-                  value:
-                    success: false
-                    error: "Account is temporarily locked. Please try again later."
-                    error_type: "account_locked"
-                accountDisabled:
-                  summary: Account disabled by administrator
-                  value:
-                    success: false
-                    error: "This account has been disabled."
-                    error_type: "account_disabled"
-                accountDeleted:
-                  summary: Account has been deleted
-                  value:
-                    success: false
-                    error: "This account has been deleted."
-                    error_type: "account_deleted"
-                accountDeletionExpired:
-                  summary: Deletion grace period has expired
-                  value:
-                    success: false
-                    error: "This account has been scheduled for deletion and the grace period has expired."
-                    error_type: "account_deletion_expired"
         '429':
           description: |
             Rate limit exceeded (too many login attempts in the current window).
-            Distinct from `403 account_locked`: this is infrastructure-level
-            throttling, not persisted account state, and carries no `error_type`.
-            This is the first 429 in this spec to declare a `Retry-After`
-            response header — future rate-limited endpoints should follow the
-            same pattern.
+            Infrastructure-level throttling, not credential rejection (for that
+            see 401), and carries no `error_type`. This is the first 429 in this
+            spec to declare a `Retry-After` response header — future
+            rate-limited endpoints should follow the same pattern.
           headers:
             Retry-After:
               description: Seconds to wait before retrying. Delta-seconds (RFC 9110).
@@ -3217,6 +3264,110 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
 
+  /api/auth/resend-verification:
+    post:
+      summary: Resend the account verification email
+      description: |
+        Re-dispatches the registration verification email for an account
+        that exists but is not yet verified — the recovery path for a user
+        who lost or never received the original email (there is otherwise no
+        way to obtain a fresh verification token). Reuses the same token-mint
+        + Registration mailer as `POST /api/auth/register`.
+
+        **Anti-enumeration: this endpoint ALWAYS returns `200`**, even when
+        the email does not correspond to any account OR the account is
+        already verified. Callers cannot use the response to discover whether
+        an account exists or its verified-state. The only non-success
+        responses are structured input validation (`422`) and rate-limiting
+        (`429`).
+      operationId: resendVerificationEmail
+      security: []  # anonymous (pre-authentication recovery entry point)
+      tags:
+        - Auth
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - email
+              properties:
+                email:
+                  type: string
+                  format: email
+            example:
+              email: "user@example.com"
+      responses:
+        '200':
+          description: |
+            Request accepted. A fresh verification email is dispatched only
+            if the address maps to an existing UNVERIFIED account; the
+            response shape is identical either way (anti-enumeration — does
+            not reveal account existence or verified-state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EmptySuccessEnvelope'
+              example:
+                success: true
+                data: {}
+        '400':
+          description: Request body is invalid (malformed JSON, wrong field types, or body too large).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                success: false
+                error: "Request body is invalid."
+        '422':
+          description: |
+            Structured input validation failure (malformed `email`) —
+            `ValidationErrorEnvelope` (`error_type: validation_error`).
+
+            Deliberately does NOT expose the `verify-email` domain-reject
+            (`unprocessable_entity` / `AuthRejectionEnvelope`) shape — that
+            would leak account-existence / verified-state, defeating the
+            anti-enumeration guarantee. (Mirrors `forgot-password`.)
+          content:
+            application/json:
+              schema:
+                # Kept as a single-member `oneOf` (rather than a bare `$ref`) so
+                # the flip from the planned-state 2-member union reads to oasdiff
+                # as a covariant-safe `response-body-one-of-removed` (info), not
+                # a `response-body-type-changed`. Room to re-add branches later.
+                oneOf:
+                  - $ref: '#/components/schemas/ValidationErrorEnvelope'
+              example:
+                success: false
+                error_type: validation_error
+                error: "Validation failed"
+                details:
+                  - field: "email"
+                    message: "This value is not a valid email address."
+        '429':
+          description: |
+            Rate limit exceeded (too many resend requests in the current
+            window). Carries a `Retry-After` response header.
+          headers:
+            Retry-After:
+              description: Seconds to wait before retrying. Delta-seconds (RFC 9110).
+              schema:
+                type: integer
+                minimum: 0
+              example: 60
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: Internal server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+
   /api/auth/forgot-password:
     post:
       summary: Request a password-reset email
@@ -3903,9 +4054,12 @@ paths:
       responses:
         '200':
           description: |
-            Profile updated. `name_changed` and `email_change_requested`
-            flag which mutations took effect; an email change is pending
-            confirmation rather than applied.
+            Profile updated. `name_changed` reports whether the display name
+            changed. `email_change_requested` signals the email-change flow
+            was accepted and a confirmation dispatched to the new address — it
+            is returned uniformly whether or not that address is already
+            registered, so the response never discloses account existence. The
+            email change is pending confirmation, not applied.
           content:
             application/json:
               schema:
@@ -3984,17 +4138,6 @@ paths:
               example:
                 success: false
                 error: "USER_NOT_FOUND"
-        '409':
-          description: |
-            The requested email is already claimed by another account
-            (`error: EMAIL_TAKEN`).
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorEnvelope'
-              example:
-                success: false
-                error: "EMAIL_TAKEN"
         '422':
           description: |
             Structured input validation failure (`ValidationErrorEnvelope`,
@@ -5583,6 +5726,25 @@ components:
           const: upload
         file_id:
           $ref: '#/components/schemas/UuidV7'
+        declared_duration_seconds:
+          type:
+            - number
+            - "null"
+          minimum: 0
+          description: |
+            OPTIONAL client-declared media duration in seconds, measured on the
+            client **before** upload (e.g. the browser's
+            `HTMLVideoElement.duration`). A **routing hint** for long-form
+            classification only ([`frlwBuQ5`](https://trello.com/c/frlwBuQ5)):
+            the server prefers its own authoritative media probe and falls back
+            to this value **only when the async probe duration is null** (e.g.
+            the probe has not completed at classification time). It never
+            overrides a successful probe, and is not billed against — duration
+            billing uses the probed value. Omit (or `null`) when unknown —
+            **absent behaves exactly as today** (probe-only). Ignored for
+            non-timed media. Only meaningful on an `upload` source (the one the
+            client measured locally); other source leaves do not carry it.
+          example: 187.5
 
     JobOutputSource:
       type: object
@@ -7409,51 +7571,72 @@ components:
         - account_deleted
         - account_deletion_expired
         - authentication_required
+        - reauthentication_required
         - api_key_invalid
-        - api_key_revoked
       description: |
         Machine-readable discriminator for auth HTTP errors (401/403). Distinct
         from rate-limit 429 responses, which carry no `error_type` and use the
         plain `ErrorEnvelope` with a `Retry-After` header.
 
-        Values are emitted by three auth mechanisms on the server:
+        Values are emitted by these auth mechanisms on the server:
 
         - **Login** (`POST /api/auth/login`) — password-based authentication.
+          Emits `invalid_credentials` ONLY (all account-status failures
+          collapse into it; see Mc6wiUzc).
         - **`ApiEntryPoint`** — challenge emitted on any protected route
           when no authenticated principal is present.
         - **`ApiKeyAuthenticator`** — validates `Authorization: Bearer <key>`
           headers on the `api` firewall.
+        - **`AccountStatusEnforcerListener`** — per-request live-session
+          enforcement (ticket e8eSElvD): returns `403 account_*` on an
+          authenticated stateful request when the account is revoked
+          mid-session.
 
         Per-value attribution:
 
-        - `invalid_credentials` (Login): wrong password, OR correct password on
-          an unverified account. The two cases are intentionally collapsed to
-          avoid leaking account existence on the machine-readable channel;
-          this keeps the login path consistent with the backend's registration
-          and password-reset flows, both of which are also anti-enumeration
-          (no existence leak on duplicate email or unknown account).
-        - `account_locked` (Login OR `ApiKeyAuthenticator`): account is in a
-          persisted locked state (e.g. set after repeated failures on the
-          server side). Can occur on both mechanisms when the underlying
-          account is locked, regardless of credential validity.
-        - `account_disabled` (Login OR `ApiKeyAuthenticator`): account has been
-          disabled by an administrator.
-        - `account_deleted` (Login OR `ApiKeyAuthenticator`): account has been
-          deleted.
-        - `account_deletion_expired` (Login OR `ApiKeyAuthenticator`): grace
-          period expired after a user-initiated deletion request.
-        - `authentication_required` (`ApiEntryPoint`): unauthenticated
-          request reached an endpoint that requires authentication.
-          Emitted as a 401 challenge; no credentials were presented or
-          the session is absent/expired. (Endpoint-level auth requirements
-          are not declared in this spec yet — tracked as a separate
-          housekeeping item to wire `security` requirements per route.)
-        - `api_key_invalid` (`ApiKeyAuthenticator`): API key not found, or the
-          key resolves to a user that does not exist. The two cases are
-          intentionally collapsed for anti-enumeration (same reasoning as
-          `invalid_credentials`).
-        - `api_key_revoked` (`ApiKeyAuthenticator`): API key was found but is
-          no longer active (`isActive() === false`).
+        - `invalid_credentials` (Login): wrong password, correct password on an
+          unverified account, OR any persisted account-status failure (locked /
+          disabled / deleted / deletion-expired). **All collapsed into this one
+          value** so login never leaks account existence or state
+          (anti-enumeration; Mc6wiUzc) — consistent with the registration +
+          password-reset flows. The `account_*` values below are therefore NOT
+          emitted on login.
+        - `account_locked` (`ApiKeyAuthenticator` OR `AccountStatusEnforcerListener`):
+          account is in a persisted locked state. Emitted as `403` when a VALID
+          API key's owner is locked, or when the live-session enforcer acts on a
+          locked account — NOT on login (a login attempt against a locked
+          account collapses to `401 invalid_credentials`). A valid key / live
+          session only reveals the caller's OWN status, so this is not an
+          enumeration oracle.
+        - `account_disabled` (same surfaces): account disabled by an administrator.
+        - `account_deleted` (same surfaces): account has been deleted.
+        - `account_deletion_expired` (same surfaces): grace period expired after
+          a user-initiated deletion request.
+        - `authentication_required` (`ApiEntryPoint` OR `ApiKeyAuthenticator`
+          fallback): **no usable credential** was resolved. Two surfaces —
+          (a) `ApiEntryPoint` challenges an unauthenticated request that reached
+          an endpoint requiring authentication (no credential / absent session);
+          (b) `ApiKeyAuthenticator` falls back to this value for an
+          otherwise-unmodelled bearer-auth failure. A session that is **present
+          but stale/expired** is NOT this value — that is
+          `reauthentication_required` (below). (Endpoint-level auth requirements
+          are not declared in this spec yet — tracked as a separate housekeeping
+          item to wire `security` requirements per route.)
+        - `reauthentication_required`: a session credential was **present**
+          on the request but is stale / no longer valid (expired, revoked,
+          or its owner no longer resolves). Distinct from
+          `authentication_required` (no credential presented at all): the
+          caller *was* authenticated and must re-authenticate. Emitted as a
+          401 by endpoints that **fail closed** on a stale session rather
+          than degrading to anonymous — e.g. `POST /api/workflows`
+          (apxXxptO), which would otherwise silently create an anonymous,
+          null-owner workflow. Clients should surface a re-auth prompt and
+          retry, preserving in-progress work.
+        - `api_key_invalid` (`ApiKeyAuthenticator`): API key not found, resolves
+          to a user that does not exist, OR is no longer active (revoked). All
+          cases are intentionally collapsed for anti-enumeration (same reasoning
+          as `invalid_credentials`); the former distinct `api_key_revoked` value
+          was removed in Mc6wiUzc.
 
     AuthErrorResponse:
       description: |
@@ -8574,6 +8757,23 @@ components:
             `long_form_preferred`); defaults to `auto` when omitted.
             Server is the final authority on routing — `class_hint`
             is advisory + policy-shaping, NOT a backend selector.
+        notify:
+          $ref: '#/components/schemas/NotifyConfig'
+          description: |
+            Optional per-job completion-notification config
+            (channel-agnostic). Currently exposes the `email` channel: the
+            API emails the configured recipients when the selected workflow
+            events occur, with a **server-composed** presigned `/downloads`
+            link to the results — the request carries recipients + event
+            selection only.
+
+            **Advertised-ahead (contract-first, ticket
+            [`IQtEwVET`](https://trello.com/c/IQtEwVET)):** the completion-
+            notification dispatch engine is built separately; until it ships
+            the API returns `feature_not_available` (422) for any `notify`
+            use. Reuses the `CallbackEventType` vocabulary shared with
+            `callback_events` (webhook) — email and webhook are two channels
+            off one dispatch engine.
 
     JobDefinition:
       type: object
@@ -10224,10 +10424,13 @@ components:
           minimum: 0
           description: |
             OPTIONAL. Original input size in bytes — the left side of the
-            list-row savings readout. For multi-input jobs, the combined
-            size of all source inputs. Pair with `output_size_bytes` to
-            render "1.2 MB → 480 KB (↓60%)" without a drill-in. Absent when
-            not yet known or not applicable.
+            list-row savings readout. This is the job's DIRECT / base
+            originating-upload size (a single base input), **not** a recursive
+            sum of all source inputs; it is omitted for jobs whose input is an
+            upstream `job_output` (merge / derived jobs). Pair with
+            `output_size_bytes` to render "1.2 MB → 480 KB (↓60%)" without a
+            drill-in — a non-authoritative at-a-glance summary. Absent when not
+            yet known or not applicable.
           example: 1258291
         output_size_bytes:
           type: integer
@@ -10575,12 +10778,14 @@ components:
           format: int64
           minimum: 0
           description: |
-            OPTIONAL. Original input size in bytes for this job (combined
-            source size for multi-input jobs). The drill-in mirror of
-            `WorkflowSummaryJob.input_size_bytes`; the input side of the
-            savings readout (output sizes remain on the per-operation
-            `OperationResult.size_bytes` / `GET /{id}/downloads`). OPTIONAL
-            for the same webhook-payload reason as `input_filename`.
+            OPTIONAL. Original input size in bytes for this job — the job's
+            DIRECT / base originating-upload size (a single base input),
+            **not** a recursive sum of all source inputs; omitted for jobs
+            whose input is an upstream `job_output` (merge / derived). The
+            drill-in mirror of `WorkflowSummaryJob.input_size_bytes`; the input
+            side of the savings readout (output sizes remain on the
+            per-operation `OperationResult.size_bytes` / `GET /{id}/downloads`).
+            OPTIONAL for the same webhook-payload reason as `input_filename`.
           example: 1258291
         processing_class:
           $ref: '#/components/schemas/ProcessingClass'
@@ -12677,6 +12882,86 @@ components:
         - workflow.partially_failed
         - operation.completed
 
+    NotifyConfig:
+      type: object
+      x-availability: planned
+      description: |
+        Channel-agnostic per-job completion-notification config (ticket
+        [`IQtEwVET`](https://trello.com/c/IQtEwVET)). Currently the `email`
+        channel only; `webhook` folds onto the same dispatch engine later
+        (today webhook is configured via the top-level `callback_url` /
+        `callback_events`). **Advertised-ahead** — the API returns
+        `feature_not_available` (422) for any `notify` use until the
+        dispatch engine ships. `x-availability` is decorative per
+        ADR-0001 §1.5; the API is the authority on the 422 gate.
+
+        An **empty `notify`** (object present but no channel set) is a
+        no-op — the workflow runs normally with no notifications; it is
+        neither an error nor a dispatch trigger. Omit `notify` entirely to
+        say the same thing.
+      properties:
+        email:
+          $ref: '#/components/schemas/EmailNotify'
+          description: Email notification channel.
+
+    EmailNotify:
+      type: object
+      required:
+        - to
+      description: |
+        Email-channel completion notification. When a subscribed workflow
+        event occurs, the API emails each recipient in `to` a link to the
+        workflow's results — a **server-composed, short-lived presigned URL**
+        to the same downloadable outputs as `GET /api/workflows/{id}/downloads`.
+        The request carries recipients + event selection ONLY: the link's
+        target, contents, and expiry are determined server-side and can never
+        be supplied or influenced by the caller.
+
+        The emailed link is a time-limited **bearer capability** — anyone who
+        holds it (including anyone the email is forwarded to) can download
+        those outputs until it expires; it grants no other account access and
+        conveys no session. This is the same trust model as any presigned
+        download URL.
+
+        **Anti-abuse (security).** Because `POST /api/workflows` is callable
+        with `optional` auth, an unconstrained recipient list would be an open
+        mail-relay / spam-amplification vector. Recipients are therefore
+        subject to **server-side anti-abuse controls** — the API restricts who
+        may be emailed (the exact recipient policy, e.g. the authenticated
+        account's own verified address(es), is API/product-owned and enforced
+        server-side, NOT a caller-supplied setting) and applies send-rate
+        limits; a request whose recipients fall outside the allowed set is
+        rejected. This is part of what the `planned` gate covers until the
+        dispatch engine + its abuse controls ship.
+      properties:
+        to:
+          type: array
+          minItems: 1
+          maxItems: 10
+          description: |
+            Recipient email addresses (1–10). At least one is required when
+            `email` is present. Subject to the server-side recipient policy
+            above — the API may reject or narrow recipients outside the
+            allowed set (anti-abuse); a caller cannot email arbitrary third
+            parties.
+          items:
+            type: string
+            format: email
+        events:
+          type: array
+          description: |
+            Which workflow events trigger the email. Reuses the
+            `CallbackEventType` vocabulary shared with `callback_events`
+            (webhook) — the notify surface does NOT fork the event enum.
+            Defaults to terminal events only (mirrors the `callback_events`
+            default); `operation.completed` is opt-in for granular progress.
+          items:
+            $ref: '#/components/schemas/CallbackEventType'
+          default:
+            - "workflow.completed"
+            - "workflow.failed"
+            - "workflow.partially_failed"
+
     WebhookPayload:
       type: object
       description: |

package/operation-capabilities/operation-capabilities.json

@@ -732,5 +732,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.162.0"
+  "schema_version": "2.171.0"
 }