@celigo/api-specs 0.2.1

package/dist/notification.yml

@@ -0,0 +1,488 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Notifications
+  description: API for managing Celigo notification subscriptions — per-user alert routing for flow, connection, integration, and sync events.
+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: Notifications
+    description: |-
+      Notification subscriptions control which users receive alerts for
+      resource-level events (errors, status changes, completions) on flows,
+      connections, integrations, and syncs. Each subscription routes alerts
+      to the email of the subscribed user.
+
+      Subscriptions are account-scoped — an account admin can manage
+      subscriptions on behalf of any user, not just their own.
+
+      ## Notification schema
+
+      {% openapi-schemas spec="notification" schemas="Notification" grouped="true" %}
+paths:
+  /v1/notifications:
+    get:
+      x-internal: false
+      operationId: listNotifications
+      tags:
+        - Notifications
+      summary: List notification subscriptions
+      description: |-
+        Returns notification subscriptions for flows, connections, integrations,
+        and syncs in the account. Without the `users=all` query parameter, the response is
+        scoped to the caller's own subscriptions. With `users=all`, every user's
+        subscriptions in the account are returned.
+
+        Returns an empty response when the caller has no subscriptions in the
+        current scope. With `users=all`, an empty array is returned only in
+        accounts with zero subscriptions across all users.
+      parameters:
+        - name: users
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - all
+            x-enumDescriptions:
+              all: Return subscriptions for every user in the account.
+          description: |-
+            When set to `all`, returns subscriptions for every user in the
+            account. When omitted, returns only the caller's own subscriptions.
+      responses:
+        '200':
+          description: Array of notification subscriptions.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Notification'
+              examples:
+                mixed:
+                  summary: Subscriptions across flow / connection / integration / sync
+                  value:
+                    - _id: 612e68884d644e604724250a
+                      type: connection
+                      _connectionId: 5e5eb06fdd83ed4f8206a4ea
+                      lastModified: '2021-08-31T17:36:09.092Z'
+                      subscribedByUser:
+                        name: James Roth
+                        email: james.roth@celigo.com
+                    - _id: 698abc1234567890abcdef01
+                      type: flow
+                      _flowId: 69497fc443fc1f9a03d31bd9
+                      lastModified: '2026-04-01T12:00:00.000Z'
+                      subscribedByUser:
+                        name: Jane Doe
+                        email: jane@example.com
+                    - _id: 69e754caae7bf0aeb0f69f3a
+                      type: sync
+                      _syncId: 69e7549b0f8b6cd703e5d3b2
+                      lastModified: '2026-04-21T10:43:22.077Z'
+                      subscribedByUser:
+                        name: Bhavik Shah
+                        email: bhavik.shah@celigo.com
+        '204':
+          description: |-
+            Caller has no subscriptions in the current scope (default scope when
+            `users=all` is omitted). Not the same as 200 with `[]`.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+    put:
+      x-internal: false
+      operationId: upsertNotifications
+      tags:
+        - Notifications
+      summary: Subscribe / unsubscribe users to resource notifications
+      description: |-
+        Upserts a batch of notification subscriptions. Each item targets exactly one
+        resource (`_flowId`, `_connectionId`, or `_integrationId`) plus a
+        `subscribedByUserEmail`. `subscribed: true` creates (or keeps) the
+        subscription; `subscribed: false` removes it.
+
+        Returns a parallel array of per-item results — one entry per request item,
+        in the same order. Each result carries `statusCode` (**201** when a subscription
+        was created, **200** when updated or removed, 422 when a referenced resource
+        doesn't exist) plus an `errors[]` array on failures. An empty request body
+        returns an empty array.
+
+        The body is a bare array (maximum 500 items). Each item must carry
+        exactly one of `_flowId` / `_connectionId` / `_integrationId` /
+        `_syncId`. The response is a per-item status array; referencing a
+        non-existent resource fails that item with `statusCode: 422` but
+        does not fail the whole request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NotificationsUpsertRequest'
+            examples:
+              subscribeFlow:
+                summary: Subscribe jane@example.com to a flow
+                value:
+                  - _flowId: 69497fc443fc1f9a03d31bd9
+                    subscribed: true
+                    subscribedByUserEmail: jane@example.com
+              unsubscribeConnections:
+                summary: Unsubscribe jane from two connections
+                value:
+                  - _connectionId: 5e5eb06fdd83ed4f8206a4ea
+                    subscribed: false
+                    subscribedByUserEmail: jane@example.com
+                  - _connectionId: 5efe49fd2c1111472296f389
+                    subscribed: false
+                    subscribedByUserEmail: jane@example.com
+      responses:
+        '200':
+          description: |-
+            Per-item result array (parallel to the request). Each entry is
+            `{statusCode, errors?}` — `statusCode: 200` on success, or a non-200
+            status with an `errors[]` array on per-item failures. Overall HTTP is
+            still 200 even when individual items fail.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  description: Per-item upsert result.
+                  properties:
+                    statusCode:
+                      type: integer
+                      description: |-
+                        Per-item outcome: 200 when the subscription was created,
+                        updated, or left unchanged; 422 when the referenced
+                        resource doesn't exist (details in `errors[]`).
+                    errors:
+                      type: array
+                      description: Per-item error details — present on non-200 results.
+                      items:
+                        type: object
+                        properties:
+                          field:
+                            type: string
+                            examples:
+                              - _connectionId
+                          code:
+                            type: string
+                            examples:
+                              - invalid_ref
+                          message:
+                            type: string
+                            examples:
+                              - Please ensure that connection with 000000000000000000000001 exists for creating the notification.
+              examples:
+                allSuccess:
+                  summary: All items applied cleanly
+                  value:
+                    - statusCode: 200
+                    - statusCode: 200
+                mixed:
+                  summary: One item referenced a non-existent connection
+                  value:
+                    - statusCode: 200
+                    - statusCode: 422
+                      errors:
+                        - field: _connectionId
+                          code: invalid_ref
+                          message: Please ensure that connection with 000000000000000000000001 exists for creating the notification.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    ResourceResponse:
+      type: object
+      description: Response
+      x-celigo-ai-guidance:
+        - Core response fields shared by all Celigo resources
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the resource. Format is a 24-character hexadecimal string.
+          x-celigo-ai-guidance:
+            - |-
+              The _id is used in:
+              - API endpoints that operate on a specific resource (e.g., GET, PUT, DELETE)
+              - References from other resources (e.g., flows that use this resource)
+              - Job history and error tracking
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was created. Set automatically and cannot be modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix).
+          examples:
+            - '2023-04-01T09:15:32Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was last updated. Changes whenever any property is modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+          examples:
+            - '2023-04-15T14:30:15Z'
+        deletedAt:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was soft-deleted. When null or absent, the resource is active.
+          x-celigo-ai-guidance:
+            - Non-null means the resource is soft-deleted (in the recycle bin) — recoverable within the retention period before permanent removal.
+          examples:
+            - '2023-05-20T11:45:32Z'
+      required:
+        - _id
+    Notification:
+      type: object
+      required:
+        - _id
+        - type
+        - lastModified
+      description: |-
+        A notification subscription linking a user email to a single resource
+        (flow, connection, integration, or sync). When the resource emits an
+        alert (error, state change, etc.), the subscribed user is notified.
+      allOf:
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            type:
+              type: string
+              enum:
+                - flow
+                - connection
+                - integration
+                - sync
+              x-enumDescriptions:
+                flow: Subscription targets a flow resource.
+                connection: Subscription targets a connection resource.
+                integration: Subscription targets an integration resource.
+                sync: Subscription targets a sync resource.
+              description: |-
+                Which resource class this subscription targets. Implies which of
+                `_flowId` / `_connectionId` / `_integrationId` / `_syncId` is populated.
+            _flowId:
+              type: string
+              format: objectId
+              description: 'Flow id when `type: flow`.'
+              x-celigo-refModel: flows
+              examples:
+                - 69497fc443fc1f9a03d31bd9
+            _connectionId:
+              type: string
+              format: objectId
+              description: 'Connection id when `type: connection`.'
+              x-celigo-refModel: connections
+              examples:
+                - 5e5eb06fdd83ed4f8206a4ea
+            _integrationId:
+              type: string
+              format: objectId
+              description: 'Integration id when `type: integration`.'
+              x-celigo-refModel: integrations
+              examples:
+                - 5d2c5a8f3e9b1c4a7f6d2e80
+            _syncId:
+              type: string
+              format: objectId
+              description: 'Sync id when `type: sync`.'
+              x-celigo-refModel: syncs
+              examples:
+                - 69e7549b0f8b6cd703e5d3b2
+            subscribedByUser:
+              type: object
+              description: Minimal user descriptor for whoever owns this subscription.
+              properties:
+                name:
+                  type: string
+                  description: Display name of the subscribed user.
+                  examples:
+                    - James Roth
+                email:
+                  type: string
+                  format: email
+                  description: Email address the notifications are routed to.
+                  examples:
+                    - james.roth@celigo.com
+    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
+    NotificationsUpsertRequest:
+      type: array
+      maxItems: 500
+      description: |-
+        Bare array (no wrapping envelope) of upsert items. Each item targets a
+        single resource and flips subscription state on or off for one user.
+      items:
+        type: object
+        description: |-
+          A single subscribe / unsubscribe directive. Set exactly one of
+          `_flowId`, `_connectionId`, `_integrationId`, or `_syncId`.
+        oneOf:
+          - required:
+              - _flowId
+          - required:
+              - _connectionId
+          - required:
+              - _integrationId
+          - required:
+              - _syncId
+        properties:
+          _flowId:
+            type: string
+            format: objectId
+            description: Flow id to subscribe / unsubscribe. Set exactly one of `_flowId` / `_connectionId` / `_integrationId` / `_syncId`.
+            x-celigo-refModel: flows
+            examples:
+              - 69497fc443fc1f9a03d31bd9
+          _connectionId:
+            type: string
+            format: objectId
+            description: Connection id to subscribe / unsubscribe.
+            x-celigo-refModel: connections
+            examples:
+              - 5e5eb06fdd83ed4f8206a4ea
+          _integrationId:
+            type: string
+            format: objectId
+            description: Integration id to subscribe / unsubscribe.
+            x-celigo-refModel: integrations
+            examples:
+              - 5d2c5a8f3e9b1c4a7f6d2e80
+          _syncId:
+            type: string
+            format: objectId
+            description: Sync id to subscribe / unsubscribe.
+            x-celigo-refModel: syncs
+            examples:
+              - 69e7549b0f8b6cd703e5d3b2
+          subscribed:
+            type: boolean
+            description: |-
+              `true` creates the subscription (or no-ops if it already exists);
+              `false` removes it.
+          subscribedByUserEmail:
+            type: string
+            format: email
+            description: |-
+              Email of the user whose subscription is being modified. Must match a
+              user in the account — unknown emails are silently ignored (no-op).
+            examples:
+              - jane@example.com
+        required:
+          - subscribed
+          - subscribedByUserEmail
+  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
+x-enable-proxy: true
+x-internal: false