@celigo/api-specs 0.2.103 → 0.2.105

package/dist/alert.yml

@@ -0,0 +1,1226 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Alerts
+  description: |-
+    API for managing proactive alerts — account-configured rules that notify
+    recipients when flows exceed a long-runtime threshold.
+
+    Recipients are supplied as `_recipientEmails` on write; the API resolves
+    emails to users (creating invites or granting integration access when
+    needed) and persists `_recipientUserIds`. Soft-deleted alerts are excluded
+    from list and get responses.
+
+    The Alerts page UI list uses `GET /api/bff/alerts` (grouped by type); that
+    route is UI-only and is not part of this public `/v1` contract.
+
+    ## Alert schema
+
+    {% openapi-schemas spec="alert" schemas="Alert" grouped="true" %}
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: Alerts
+    description: |-
+      Proactive alerts define long-runtime thresholds and recipients for flows
+      or whole integrations. Create, list, update, and delete alerts; bulk-update
+      recipients across many alerts; and fetch per-alert audit history.
+
+      ## Alert schema
+
+      {% openapi-schemas spec="alert" schemas="Alert" grouped="true" %}
+paths:
+  /v1/alerts:
+    get:
+      x-internal: false
+      operationId: listAlerts
+      tags:
+        - Alerts
+      summary: List alerts
+      description: |-
+        Returns proactive alerts for the account. Soft-deleted alerts are excluded.
+        Requires permission `get:alert:models`. Returns `403` when the
+        `ENABLE_PROACTIVE_ALERTS` feature flag is off.
+
+        With `populate=true`, nested `flow` / `integration` summaries and
+        recipient `{ _id, name, email }` objects are returned. Without populate,
+        foreign keys are raw ObjectIds.
+
+        Tile-level (shared) users must include `_integrationId`.
+      parameters:
+        - name: populate
+          in: query
+          required: false
+          description: When `true`, populate flow, integration, and recipient user fields.
+          schema:
+            type: string
+            enum:
+              - 'true'
+            x-enumDescriptions:
+              'true': Return nested objects for referenced resources.
+        - name: type
+          in: query
+          required: false
+          description: Filter by alert type.
+          schema:
+            type: string
+            enum:
+              - long-runtime
+            x-enumDescriptions:
+              long-runtime: Long-runtime threshold alerts.
+        - name: _integrationId
+          in: query
+          required: false
+          description: Filter by integration id. Required for tile-level (shared) users.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 5e5eb06fdd83ed4f8206a4ea
+        - name: _flowId
+          in: query
+          required: false
+          description: Filter by flow id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: flows
+            examples:
+              - 69497fc443fc1f9a03d31bd9
+        - name: _recipientUserId
+          in: query
+          required: false
+          description: Filter alerts that include this user as a recipient.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: users
+            examples:
+              - 624cb0346309dc3a543733a2
+        - name: lastTriggeredAt
+          in: query
+          required: false
+          description: |-
+            Filter by last triggered time. Use `never` for alerts that have not
+            fired. Prefer `lastTriggeredAt_gte` / `lastTriggeredAt_lte` for ranges.
+          schema:
+            type: string
+            examples:
+              - never
+        - name: lastTriggeredAt_gte
+          in: query
+          required: false
+          description: Include alerts last triggered at or after this ISO-8601 timestamp.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-05-01T00:00:00.000Z'
+        - name: lastTriggeredAt_lte
+          in: query
+          required: false
+          description: Include alerts last triggered at or before this ISO-8601 timestamp.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-06-01T00:00:00.000Z'
+      responses:
+        '200':
+          description: Array of alerts (empty array when none match).
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Alert'
+              examples:
+                unpopulated:
+                  summary: Unpopulated list
+                  value:
+                    - _id: 674a1b2c3d4e5f6789012345
+                      type: long-runtime
+                      _userId: 624cb0346309dc3a543733a2
+                      _integrationId: 5e5eb06fdd83ed4f8206a4ea
+                      _flowId: 69497fc443fc1f9a03d31bd9
+                      longRuntime:
+                        thresholdMinutes: 30
+                      _recipientUserIds:
+                        - 624cb0346309dc3a543733a2
+                      lastTriggeredAt: null
+                      createdAt: '2026-05-01T10:00:00.000Z'
+                      lastModified: '2026-05-01T10:00:00.000Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+    post:
+      x-internal: false
+      operationId: createAlert
+      tags:
+        - Alerts
+      summary: Create an alert
+      description: |-
+        Creates a proactive alert. Validates type, flow/integration, and duplicate
+        constraints, then resolves `_recipientEmails` to `_recipientUserIds` and
+        dual-writes the long-runtime threshold onto the related flow document(s).
+
+        Requires permission `put:alert:models`. Returns `403` when
+        `ENABLE_PROACTIVE_ALERTS` is off. Response is always unpopulated.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AlertCreateRequest'
+            examples:
+              flowLevel:
+                summary: Flow-level long-runtime alert
+                value:
+                  type: long-runtime
+                  _flowId: 69497fc443fc1f9a03d31bd9
+                  longRuntime:
+                    thresholdMinutes: 30
+                  _recipientEmails:
+                    - ops@example.com
+                    - jane@example.com
+              integrationLevel:
+                summary: Integration-level long-runtime alert
+                value:
+                  type: long-runtime
+                  _integrationId: 5e5eb06fdd83ed4f8206a4ea
+                  longRuntime:
+                    thresholdMinutes: 60
+                  _recipientEmails:
+                    - ops@example.com
+      responses:
+        '201':
+          description: Created alert (unpopulated ObjectIds).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Alert'
+              examples:
+                default:
+                  value:
+                    _id: 674a1b2c3d4e5f6789012345
+                    type: long-runtime
+                    _userId: 624cb0346309dc3a543733a2
+                    _integrationId: 5e5eb06fdd83ed4f8206a4ea
+                    _flowId: 69497fc443fc1f9a03d31bd9
+                    longRuntime:
+                      thresholdMinutes: 30
+                    _recipientUserIds:
+                      - 624cb0346309dc3a543733a2
+                      - 6356f24327114d57ab843e1f
+                    lastTriggeredAt: null
+                    createdAt: '2026-05-01T10:00:00.000Z'
+                    lastModified: '2026-05-01T10:00:00.000Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '409':
+          description: An alert with the same type, flow, and integration already exists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                duplicate:
+                  value:
+                    errors:
+                      - code: ROUTES_ALERT_DUPLICATE
+                        message: An alert already exists for this flow / integration and type.
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/alerts/bulk/recipients:
+    patch:
+      x-internal: false
+      operationId: bulkUpdateAlertRecipients
+      tags:
+        - Alerts
+      summary: Bulk update alert recipients
+      description: |-
+        Adds or removes recipients across many alerts in one call. Provide either
+        `_alertIds` or `_integrationId` (not both). Both `add` and `remove` accept
+        `_recipientEmails`.
+
+        Full success returns `204` with no body. Partial failure returns `200` with
+        `{ failed: [...] }` only — successful alerts are omitted. There is no
+        `success` or `skipped` array.
+
+        Requires permission `put:alert:models`. Returns `403` when
+        `ENABLE_PROACTIVE_ALERTS` is off. `add` is limited to one integration per
+        call; `remove` may span integrations.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AlertBulkRecipientsRequest'
+            examples:
+              addByIds:
+                summary: Add a recipient to specific alerts
+                value:
+                  action: add
+                  _alertIds:
+                    - 674a1b2c3d4e5f6789012345
+                    - 674a1b2c3d4e5f6789012346
+                  _recipientEmails:
+                    - ops@example.com
+              removeByIntegration:
+                summary: Remove a recipient from all alerts in an integration
+                value:
+                  action: remove
+                  _integrationId: 5e5eb06fdd83ed4f8206a4ea
+                  _recipientEmails:
+                    - ops@example.com
+      responses:
+        '200':
+          description: |-
+            One or more alerts failed. Body contains only `failed[]`; each entry
+            includes `_id`, optional `affectedRecipientEmails`, and `errors[]`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AlertBulkRecipientsFailed'
+              examples:
+                lastRecipient:
+                  summary: Could not remove the last recipient from one alert
+                  value:
+                    failed:
+                      - _id: 674a1b2c3d4e5f6789012345
+                        affectedRecipientEmails:
+                          - ops@example.com
+                        errors:
+                          - code: ROUTES_ALERT_BULK_LAST_RECIPIENT
+                            message: Cannot remove the last recipient from an alert.
+        '204':
+          description: All targeted alerts updated successfully.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          description: No alerts exist for the specified `_integrationId`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                noAlerts:
+                  value:
+                    errors:
+                      - code: ROUTES_ALERT_BULK_NO_ALERTS_FOR_INTEGRATION
+                        message: No alerts found for this integration.
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/alerts/{_id}:
+    get:
+      x-internal: false
+      operationId: getAlertById
+      tags:
+        - Alerts
+      summary: Get an alert
+      description: |-
+        Returns a single proactive alert by id. Soft-deleted alerts return `404`.
+        Requires permission `get:alert:model`. Returns `403` when
+        `ENABLE_PROACTIVE_ALERTS` is off.
+
+        With `populate=true`, nested flow / integration / recipient objects are
+        returned; otherwise foreign keys are raw ObjectIds.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Alert id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: alerts
+            examples:
+              - 674a1b2c3d4e5f6789012345
+        - name: populate
+          in: query
+          required: false
+          description: When `true`, populate flow, integration, and recipient user fields.
+          schema:
+            type: string
+            enum:
+              - 'true'
+            x-enumDescriptions:
+              'true': Return nested objects for referenced resources.
+      responses:
+        '200':
+          description: Alert object.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Alert'
+              examples:
+                default:
+                  value:
+                    _id: 674a1b2c3d4e5f6789012345
+                    type: long-runtime
+                    _userId: 624cb0346309dc3a543733a2
+                    _integrationId: 5e5eb06fdd83ed4f8206a4ea
+                    _flowId: 69497fc443fc1f9a03d31bd9
+                    longRuntime:
+                      thresholdMinutes: 30
+                    _recipientUserIds:
+                      - 624cb0346309dc3a543733a2
+                    lastTriggeredAt: null
+                    createdAt: '2026-05-01T10:00:00.000Z'
+                    lastModified: '2026-05-01T10:00:00.000Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      operationId: updateAlert
+      tags:
+        - Alerts
+      summary: Update an alert
+      description: |-
+        Replace-all update of threshold and recipients. `type`, `_flowId`, and
+        `_integrationId` are immutable. Resolves `_recipientEmails` the same way
+        as create, then dual-writes the updated threshold to related flow(s).
+
+        Requires permission `put:alert:models`. Returns `403` when
+        `ENABLE_PROACTIVE_ALERTS` is off. Response is always unpopulated.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Alert id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: alerts
+            examples:
+              - 674a1b2c3d4e5f6789012345
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AlertUpdateRequest'
+            examples:
+              default:
+                value:
+                  longRuntime:
+                    thresholdMinutes: 45
+                  _recipientEmails:
+                    - ops@example.com
+                    - jane@example.com
+      responses:
+        '200':
+          description: Updated alert (unpopulated ObjectIds).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Alert'
+              examples:
+                default:
+                  value:
+                    _id: 674a1b2c3d4e5f6789012345
+                    type: long-runtime
+                    _userId: 624cb0346309dc3a543733a2
+                    _integrationId: 5e5eb06fdd83ed4f8206a4ea
+                    _flowId: 69497fc443fc1f9a03d31bd9
+                    longRuntime:
+                      thresholdMinutes: 45
+                    _recipientUserIds:
+                      - 624cb0346309dc3a543733a2
+                      - 6356f24327114d57ab843e1f
+                    lastTriggeredAt: null
+                    createdAt: '2026-05-01T10:00:00.000Z'
+                    lastModified: '2026-05-15T14:30:00.000Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      operationId: deleteAlert
+      tags:
+        - Alerts
+      summary: Delete an alert
+      description: |-
+        Soft-deletes an alert and clears `__longRuntimeThresholdMinutes` on the
+        related flow document(s). Requires permission `put:alert:models`. Returns
+        `403` when `ENABLE_PROACTIVE_ALERTS` is off.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Alert id.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: alerts
+            examples:
+              - 674a1b2c3d4e5f6789012345
+      responses:
+        '204':
+          description: Alert soft-deleted.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/alerts/{_id}/audit:
+    get:
+      x-internal: false
+      operationId: getAlertAudit
+      tags:
+        - Alerts
+      summary: Get audit log for an alert
+      description: |-
+        Returns the change history for an alert. Each entry records a mutation
+        event with who made the change, when, and which fields were affected.
+
+        Requires permission to read the alert (`get:alert:model`). Returns `403`
+        when `ENABLE_PROACTIVE_ALERTS` is off or the caller lacks access.
+      parameters:
+        - name: _id
+          in: path
+          description: Alert ID.
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: alerts
+            examples:
+              - 674a1b2c3d4e5f6789012345
+        - name: limit
+          in: query
+          description: Maximum number of audit entries to return per page.
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+            examples:
+              - 100
+        - name: after
+          in: query
+          required: false
+          description: |-
+            Opaque pagination cursor for the next page. Take it from the `after` value in the `Link`
+            response header's `rel="next"` URL rather than constructing it.
+          schema:
+            type: string
+            examples:
+              - W3siJGRhdGUiOiIyMDI2LTA1LTAxVDAwOjAwOjAwLjAwMFoifSwiNjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIl0
+        - name: from
+          in: query
+          required: false
+          description: Only return entries at or after this timestamp.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-05-01T00:00:00.000Z'
+        - name: to
+          in: query
+          required: false
+          description: Only return entries at or before this timestamp.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-06-01T00:00:00.000Z'
+      responses:
+        '200':
+          description: Audit entries for the alert.
+          headers:
+            Link:
+              description: |-
+                Pagination link header. When more results exist, includes
+                `rel="next"` with an `after` cursor.
+              schema:
+                type: string
+                examples:
+                  - </v1/alerts/674a1b2c3d4e5f6789012345/audit?after=W3siJGRhdGUiOiIyMDI2LTA1LTAxVDAwOjAwOjAwLjAwMFoifSwiNjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIl0>; rel="next"
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    _id:
+                      type: string
+                      format: objectId
+                      description: Audit entry id.
+                      examples:
+                        - 69e38cb1a749d34a9732a270
+                    resourceType:
+                      type: string
+                      description: Resource type for this entry.
+                      enum:
+                        - alert
+                      x-enumDescriptions:
+                        alert: Alert resource.
+                      examples:
+                        - alert
+                    _resourceId:
+                      type: string
+                      format: objectId
+                      x-celigo-refModel: alerts
+                      description: Alert id.
+                      examples:
+                        - 674a1b2c3d4e5f6789012345
+                    event:
+                      type: string
+                      description: Mutation event type.
+                      enum:
+                        - create
+                        - update
+                        - delete
+                      x-enumDescriptions:
+                        create: Alert was created.
+                        update: Alert was modified.
+                        delete: Alert was soft-deleted.
+                      examples:
+                        - update
+                    source:
+                      type: string
+                      description: How the change was initiated.
+                      enum:
+                        - api
+                        - ui
+                        - system
+                      x-enumDescriptions:
+                        api: Change made via the REST API.
+                        ui: Change made through the Celigo UI.
+                        system: Change made by an automated platform process.
+                    time:
+                      type: string
+                      format: date-time
+                      description: When the change occurred.
+                      examples:
+                        - '2026-04-18T13:52:49.729Z'
+                    byUser:
+                      type: object
+                      description: User who made the change.
+                      properties:
+                        _id:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: users
+                          description: User ID.
+                          examples:
+                            - 624cb0346309dc3a543733a2
+                        email:
+                          type: string
+                          format: email
+                          description: User email address.
+                          examples:
+                            - user@example.com
+                        name:
+                          type: string
+                          description: User display name.
+                          examples:
+                            - Tyler Lamparter
+                    fieldChanges:
+                      type: array
+                      description: Fields that were modified.
+                      items:
+                        type: object
+                        properties:
+                          fieldPath:
+                            type: string
+                            description: Dot-notation path of the changed field.
+                            examples:
+                              - longRuntime.thresholdMinutes
+                          oldValue:
+                            description: Previous value (absent on create).
+                          newValue:
+                            description: New value (absent on delete).
+                    deletedInfo:
+                      type: object
+                      description: Metadata about the deleted resource. Present on `delete` events.
+                      properties:
+                        name:
+                          type: string
+                          description: Name of the resource at the time of deletion.
+              examples:
+                default:
+                  value:
+                    - _id: 69e38cb1a749d34a9732a270
+                      resourceType: alert
+                      _resourceId: 674a1b2c3d4e5f6789012345
+                      source: api
+                      event: update
+                      time: '2026-04-18T13:52:49.729Z'
+                      byUser:
+                        _id: 624cb0346309dc3a543733a2
+                        email: user@example.com
+                        name: Tyler Lamparter
+                      fieldChanges:
+                        - fieldPath: longRuntime.thresholdMinutes
+                          oldValue: 30
+                          newValue: 45
+        '204':
+          description: No audit entries exist for this alert.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    Alert:
+      type: object
+      description: |-
+        Proactive alert configuration. Soft-deleted alerts are omitted from list
+        and get responses. With `populate=true` on GET, `_flowId` and
+        `_integrationId` stay ObjectId strings and the `flow` / `integration`
+        enrichment objects are added alongside them; `_recipientUserIds` entries
+        become `{ _id, name, email }`. POST and PUT always return the unpopulated
+        shape.
+      required:
+        - _id
+        - type
+        - _userId
+        - _integrationId
+        - longRuntime
+        - _recipientUserIds
+        - createdAt
+        - lastModified
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the alert.
+          examples:
+            - 674a1b2c3d4e5f6789012345
+        type:
+          type: string
+          description: Alert type.
+          enum:
+            - long-runtime
+          x-enumDescriptions:
+            long-runtime: Notify when a flow run exceeds the configured runtime threshold.
+          examples:
+            - long-runtime
+        _userId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: users
+          description: Account owner user id for the alert.
+          examples:
+            - 624cb0346309dc3a543733a2
+        _integrationId:
+          type: string
+          format: objectId
+          x-celigo-refModel: integrations
+          description: |-
+            Integration the alert belongs to. Always an ObjectId string. With
+            `populate=true` on an integration-level alert, a sibling `integration`
+            object `{ flowCount }` is added; this id is not replaced.
+          examples:
+            - 5e5eb06fdd83ed4f8206a4ea
+        _flowId:
+          type: string
+          format: objectId
+          x-celigo-refModel: flows
+          description: |-
+            Flow for a flow-level alert; omitted on integration-level alerts.
+            Always an ObjectId string — with `populate=true` the display fields
+            arrive in the sibling `flow` object instead of replacing this value.
+          examples:
+            - 69497fc443fc1f9a03d31bd9
+        longRuntime:
+          type: object
+          description: Configuration for `long-runtime` alerts.
+          required:
+            - thresholdMinutes
+          properties:
+            thresholdMinutes:
+              type: integer
+              minimum: 5
+              maximum: 59940
+              description: Runtime threshold in minutes. Runs at or above this duration trigger the alert.
+              examples:
+                - 30
+        _recipientUserIds:
+          type: array
+          description: |-
+            Recipient user ids. Unpopulated responses return ObjectId strings;
+            with `populate=true`, each entry is `{ _id, name, email }`.
+          minItems: 1
+          items:
+            oneOf:
+              - type: string
+                format: objectId
+                x-celigo-refModel: users
+                examples:
+                  - 624cb0346309dc3a543733a2
+              - type: object
+                required:
+                  - _id
+                properties:
+                  _id:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: users
+                  name:
+                    type: string
+                    examples:
+                      - Jane Doe
+                  email:
+                    type: string
+                    format: email
+                    examples:
+                      - jane@example.com
+        flow:
+          type: object
+          readOnly: true
+          description: |-
+            Flow enrichment object. Present on populated GET responses for
+            flow-level alerts only (`populate=true`). Never returned on POST or PUT.
+            Fields: `name`, `isInstanceFlow`, `flowGroupName`.
+          properties:
+            name:
+              type: string
+              description: Flow display name.
+              examples:
+                - Order sync
+            isInstanceFlow:
+              type: boolean
+              description: Whether this is an instance of an abstract (Integration App) flow.
+            flowGroupName:
+              type: string
+              description: Name of the flow grouping this flow belongs to, if any.
+        integration:
+          type: object
+          readOnly: true
+          description: |-
+            Integration enrichment object. Present on populated GET responses for
+            integration-level alerts only (`populate=true`, no `_flowId`). Only
+            `flowCount` is returned (not `name`).
+          properties:
+            flowCount:
+              type: integer
+              description: Number of non-deleted flows under this integration.
+              examples:
+                - 12
+        lastTriggeredAt:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          description: When the alert last fired. `null` when it has never triggered.
+          examples:
+            - '2026-06-01T12:00:00.000Z'
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When the alert was created.
+          examples:
+            - '2026-05-01T10:00:00.000Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When the alert was last updated.
+          examples:
+            - '2026-05-15T14:30:00.000Z'
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    AlertCreateRequest:
+      type: object
+      description: |-
+        Create a proactive alert. Recipients are supplied as `_recipientEmails`;
+        the API resolves them to `_recipientUserIds` (inviting users or granting
+        integration access when needed). Response never echoes `_recipientEmails`.
+
+        Either `_flowId` or `_integrationId` (or both) must be provided. When
+        `_flowId` is set, `_integrationId` may be omitted (inferred from the flow).
+        Integration-level alerts require `_integrationId` without `_flowId`.
+      required:
+        - type
+        - longRuntime
+        - _recipientEmails
+      if:
+        not:
+          required:
+            - _flowId
+      then:
+        required:
+          - _integrationId
+      properties:
+        type:
+          type: string
+          description: Alert type.
+          enum:
+            - long-runtime
+          x-enumDescriptions:
+            long-runtime: Notify when a flow run exceeds the configured runtime threshold.
+          examples:
+            - long-runtime
+        _flowId:
+          type: string
+          format: objectId
+          x-celigo-refModel: flows
+          description: |-
+            Flow id for a flow-level alert. When set, `_integrationId` may be
+            omitted and is inferred from the flow.
+          examples:
+            - 69497fc443fc1f9a03d31bd9
+        _integrationId:
+          type: string
+          format: objectId
+          x-celigo-refModel: integrations
+          description: |-
+            Integration id. Required for integration-level alerts (no `_flowId`).
+            Required for `long-runtime` unless inferred from `_flowId`.
+          examples:
+            - 5e5eb06fdd83ed4f8206a4ea
+        longRuntime:
+          type: object
+          required:
+            - thresholdMinutes
+          properties:
+            thresholdMinutes:
+              type: integer
+              minimum: 5
+              maximum: 59940
+              description: Runtime threshold in minutes.
+              examples:
+                - 30
+        _recipientEmails:
+          type: array
+          description: |-
+            Recipient email addresses. Trimmed, lowercased, and deduplicated
+            server-side. Minimum 1; maximum controlled by `ALERT_MAX_RECIPIENT_EMAILS`
+            (default 50).
+          minItems: 1
+          maxItems: 50
+          items:
+            type: string
+            format: email
+            examples:
+              - ops@example.com
+    AlertBulkRecipientsRequest:
+      type: object
+      description: |-
+        Add or remove recipients across one or more alerts. Provide exactly one
+        target: `_alertIds` or `_integrationId` (not both). Both actions use
+        `_recipientEmails` (resolved to user ids server-side). `add` is limited to
+        one integration per call; `remove` may span integrations.
+
+        Sending both `_alertIds` and `_integrationId` returns `400`.
+      required:
+        - action
+        - _recipientEmails
+      if:
+        required:
+          - _alertIds
+      then:
+        not:
+          required:
+            - _integrationId
+      else:
+        required:
+          - _integrationId
+      properties:
+        action:
+          type: string
+          description: Whether to add or remove the listed recipients.
+          enum:
+            - add
+            - remove
+          x-enumDescriptions:
+            add: Resolve emails and `$addToSet` onto `_recipientUserIds`.
+            remove: Resolve emails and `$pull` from `_recipientUserIds`.
+          examples:
+            - add
+        _alertIds:
+          type: array
+          description: Explicit alert ids to update. Mutually exclusive with `_integrationId`.
+          minItems: 1
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: alerts
+            examples:
+              - 674a1b2c3d4e5f6789012345
+        _integrationId:
+          type: string
+          format: objectId
+          x-celigo-refModel: integrations
+          description: |-
+            When set, the operation applies to every alert under this integration.
+            Mutually exclusive with `_alertIds`.
+          examples:
+            - 5e5eb06fdd83ed4f8206a4ea
+        _recipientEmails:
+          type: array
+          description: Recipient emails to add or remove. Trimmed, lowercased, and deduplicated.
+          minItems: 1
+          maxItems: 50
+          items:
+            type: string
+            format: email
+            examples:
+              - ops@example.com
+    AlertBulkRecipientsFailed:
+      type: object
+      description: |-
+        Partial-failure body returned with HTTP 200 when at least one alert in the
+        bulk recipients call could not be fully updated. Full success returns 204
+        with no body.
+      required:
+        - failed
+      properties:
+        failed:
+          type: array
+          description: Per-alert failures. Successful alerts are omitted.
+          items:
+            type: object
+            required:
+              - _id
+              - errors
+            properties:
+              _id:
+                type: string
+                format: objectId
+                x-celigo-refModel: alerts
+                description: Alert id that failed.
+                examples:
+                  - 674a1b2c3d4e5f6789012345
+              affectedRecipientEmails:
+                type: array
+                description: |-
+                  Emails implicated in this failure (for example, recipients that
+                  could not be removed because they are the last remaining recipient).
+                items:
+                  type: string
+                  format: email
+                  examples:
+                    - ops@example.com
+              errors:
+                type: array
+                description: Error details for this alert.
+                minItems: 1
+                items:
+                  type: object
+                  properties:
+                    code:
+                      type: string
+                      examples:
+                        - ROUTES_ALERT_BULK_LAST_RECIPIENT
+                    message:
+                      type: string
+                      examples:
+                        - Cannot remove the last recipient from an alert.
+                    field:
+                      type: string
+                      examples:
+                        - _recipientEmails
+    AlertUpdateRequest:
+      type: object
+      description: |-
+        Replace-all update for an alert. `type`, `_flowId`, and `_integrationId`
+        are immutable and ignored if sent. Recipients are replace-all via
+        `_recipientEmails` (same resolution/invite behavior as create).
+      required:
+        - longRuntime
+        - _recipientEmails
+      properties:
+        longRuntime:
+          type: object
+          required:
+            - thresholdMinutes
+          properties:
+            thresholdMinutes:
+              type: integer
+              minimum: 5
+              maximum: 59940
+              description: Runtime threshold in minutes.
+              examples:
+                - 45
+        _recipientEmails:
+          type: array
+          description: |-
+            Full replacement recipient email list. Trimmed, lowercased, and
+            deduplicated server-side. Must contain at least one address.
+          minItems: 1
+          maxItems: 50
+          items:
+            type: string
+            format: email
+            examples:
+              - ops@example.com
+  responses:
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    403-forbidden:
+      description: |
+        Forbidden. The authenticated caller does not have permission to perform this operation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+x-enable-proxy: true
+x-internal: false