@celigo/api-specs 0.2.202 → 0.2.204

package/dist/filestorage.yml

@@ -2311,6 +2311,374 @@ paths:
                     errors:
                       - code: invalid_timestamp_format
                         message: 'Please make sure that the time provided for field: "from" is in ISO8601 time format.'
+  /v1/storage/activity:
+    get:
+      x-internal: false
+      summary: List storage activity
+      description: |-
+        Returns the environment's Celigo Storage activity log, newest entry
+        first by default. Each entry records one action against a file or
+        folder, one storage query, or one file server login, with who did it
+        and how. Results are paginated with the `Link` response header; keep
+        the same `sort_by` and `sort_order` on every page.
+      operationId: listStorageActivity
+      tags:
+        - File Storage
+      parameters:
+        - name: _resourceId
+          in: query
+          required: false
+          description: |-
+            Return only this file's or folder's history, including entries
+            recorded after it went to the recycle bin or was purged. A single
+            ID; an ID that matches no entry returns an empty list.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+            examples:
+              - 683b2a0e1c3d5f001a9e8b01
+        - name: _byUserId
+          in: query
+          required: false
+          description: |-
+            Return only entries by these actors: user IDs, file server account
+            IDs, or `system`. Repeat the parameter or send a comma-separated
+            list; at most 50 distinct values.
+          schema:
+            type: array
+            maxItems: 50
+            items:
+              type: string
+              pattern: ^([0-9a-fA-F]{24}|system)$
+            examples:
+              - - 624cb0346309dc3a543733a2
+                - system
+        - name: source
+          in: query
+          required: false
+          description: |-
+            Return only entries initiated through these channels. Repeat the
+            parameter or send a comma-separated list; at most 50 distinct values.
+          schema:
+            type: array
+            maxItems: 50
+            items:
+              type: string
+              enum:
+                - ui
+                - api
+                - cli
+                - mcp
+                - ora
+                - connector
+                - script
+                - stack
+                - sso
+                - fileserver
+                - system
+              x-enumDescriptions:
+                ui: Celigo UI
+                api: REST API
+                cli: Celigo CLI
+                mcp: MCP server tools
+                ora: Ora AI agent
+                connector: Integration apps
+                script: Scripts and hooks
+                stack: Stack code
+                sso: Single sign-on sessions
+                fileserver: SFTP through the Celigo file server
+                system: Automated platform processes
+            examples:
+              - - ui
+                - api
+        - name: action
+          in: query
+          required: false
+          description: |-
+            Return only entries for these actions. Repeat the parameter or send
+            a comma-separated list; at most 50 distinct values.
+          schema:
+            type: array
+            maxItems: 50
+            items:
+              type: string
+              enum:
+                - create
+                - upload
+                - update
+                - download
+                - move
+                - copy
+                - merge
+                - delete
+                - restore
+                - purge
+                - query
+                - login
+                - preview
+              x-enumDescriptions:
+                create: Folder created
+                upload: File uploaded or replaced
+                update: Item renamed or re-described
+                download: Download issued
+                move: Item moved
+                copy: File copied
+                merge: Folder merged
+                delete: Item sent to the recycle bin
+                restore: Item restored
+                purge: Item permanently removed
+                query: Storage SQL query
+                login: File server login
+                preview: Reserved
+            examples:
+              - - delete
+                - purge
+        - name: time_gte
+          in: query
+          required: false
+          description: |-
+            Return only entries at or after this time. ISO 8601 or epoch
+            milliseconds.
+          schema:
+            type: string
+            examples:
+              - '2026-10-01T00:00:00.000Z'
+        - name: time_lte
+          in: query
+          required: false
+          description: |-
+            Return only entries at or before this time. ISO 8601 or epoch
+            milliseconds; must not be earlier than `time_gte`.
+          schema:
+            type: string
+            examples:
+              - '2026-10-31T23:59:59.999Z'
+        - name: sort_by
+          in: query
+          required: false
+          description: Field to sort by. Only `time` is supported.
+          schema:
+            type: string
+            enum:
+              - time
+            default: time
+            x-enumDescriptions:
+              time: Sort by when the action happened, with the entry `_id` as tiebreaker
+            examples:
+              - time
+        - name: sort_order
+          in: query
+          required: false
+          description: Sort direction. The default returns the newest entry first.
+          schema:
+            type: string
+            enum:
+              - asc
+              - desc
+            default: desc
+            x-enumDescriptions:
+              asc: Oldest entry first
+              desc: Newest entry first
+            examples:
+              - desc
+        - name: pageSize
+          in: query
+          required: false
+          description: Number of entries per page. `limit` is accepted as an alias.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 100
+            examples:
+              - 100
+        - name: after
+          in: query
+          required: false
+          description: |-
+            Opaque cursor for the next page. Take it from the `Link` response
+            header's `rel="next"` URL rather than constructing it. Cannot be
+            combined with `before`.
+          schema:
+            type: string
+            examples:
+              - WyIyMDI2LTEwLTIyVDE2OjUyOjEwLjQxM1oiLCIwMWExODA1Yy1hM2FjLTdkZmYtODc2Ni05ZWU2OGM3YWE1ZjAiLCJ0aW1lIiwiZGVzYyJd
+        - name: before
+          in: query
+          required: false
+          description: |-
+            Opaque cursor for the previous page, taken from the `Link` header's
+            `rel="prev"` URL. Cannot be combined with `after`.
+          schema:
+            type: string
+            examples:
+              - WyIyMDI2LTEwLTIyVDE2OjUyOjEwLjQxM1oiLCIwMWExODA1Yy1hM2FjLTdkZmYtODc2Ni05ZWU2OGM3YWE1ZjAiLCJ0aW1lIiwiZGVzYyJd
+      responses:
+        '200':
+          description: Matching entries, an empty `items` array when none match.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination links carrying the cursor and the request's
+                filters: `<...>; rel="next"` while more entries remain, and
+                `rel="prev"` once past the first page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - items
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/StorageActivityEntry'
+              examples:
+                rename:
+                  summary: One rename entry
+                  value:
+                    items:
+                      - _id: 01a1805c-a3ac-7dff-8766-9ee68c7aa5f0
+                        time: '2026-10-22T16:52:10.413Z'
+                        _userId: 624cb0346309dc3a543733a2
+                        _byUserId: 624cb0346309dc3a543733a2
+                        byUserName: Jane Doe
+                        source: api
+                        ip: 203.0.113.24
+                        action: update
+                        _resourceId: 683b2a0e1c3d5f001a9e8b01
+                        resourceName: quarterly-report.pdf
+                        status: active
+                        type: file
+                        _integrationId: null
+                        details:
+                          previousName: report.pdf
+                          newName: quarterly-report.pdf
+        '400':
+          description: |-
+            The pagination cursor is malformed or both `after` and `before` were
+            sent (`STORAGE_INVALID_CURSOR`), or `sort_by` or `sort_order`
+            changed between pages (`STORAGE_CURSOR_SORT_MISMATCH`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                bothCursors:
+                  summary: after and before sent together
+                  value:
+                    errors:
+                      - code: STORAGE_INVALID_CURSOR
+                        message: after and before cannot both be present in the same request
+                sortMismatch:
+                  summary: Sort changed between pages
+                  value:
+                    errors:
+                      - code: STORAGE_CURSOR_SORT_MISMATCH
+                        message: sort_by or sort_order changed between pages
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '422':
+          description: |-
+            A filter is malformed or has more than 50 distinct values
+            (`STORAGE_INVALID_FILTER`), `pageSize` is out of range
+            (`STORAGE_INVALID_PAGE_SIZE`), or `sort_by` or `sort_order` is
+            unsupported (`STORAGE_INVALID_SORT`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                userIdFilter:
+                  summary: _userId sent as a filter
+                  value:
+                    errors:
+                      - code: STORAGE_INVALID_FILTER
+                        message: _userId is not a supported filter
+                invalidResourceId:
+                  summary: _resourceId is not an ObjectId
+                  value:
+                    errors:
+                      - code: STORAGE_INVALID_FILTER
+                        message: _resourceId must be a valid ObjectId
+                invalidPageSize:
+                  summary: pageSize out of range
+                  value:
+                    errors:
+                      - code: STORAGE_INVALID_PAGE_SIZE
+                        message: pageSize (or limit) must be an integer between 1 and 1000
+                invalidSort:
+                  summary: sort_by is not time
+                  value:
+                    errors:
+                      - code: STORAGE_INVALID_SORT
+                        message: 'sort_by must be one of: time'
+  /v1/storage/activity/signedURL:
+    post:
+      x-internal: false
+      summary: Export storage activity to CSV
+      description: |-
+        Writes the activity entries that match the filters to a CSV file and
+        returns a presigned link to download it. Takes the same filters as
+        `GET /v1/storage/activity` in a JSON body but no paging fields;
+        `hasMore` says when more entries matched than the export wrote.
+      operationId: exportStorageActivity
+      tags:
+        - File Storage
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/StorageActivityFilters'
+            examples:
+              lastMonthDeletes:
+                summary: Deletes and purges in October
+                value:
+                  action:
+                    - delete
+                    - purge
+                  time_gte: '2026-10-01T00:00:00.000Z'
+                  time_lte: '2026-10-31T23:59:59.999Z'
+      responses:
+        '200':
+          description: CSV written. Download it from `downloadUrl` before it expires.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StorageActivityExport'
+              examples:
+                default:
+                  value:
+                    downloadUrl: https://integrator-userdata-delete-30.s3.us-east-1.amazonaws.com/file-storage-activity-results/624cb0346309dc3a543733a2/1793155211624-d765038e.csv?X-Amz-Expires=3600&X-Amz-Signature=REDACTED
+                    expiresIn: 3600
+                    rowCount: 1250
+                    hasMore: false
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '422':
+          description: |-
+            A filter is malformed or the body carries a paging field — `pageSize`,
+            `limit`, `after`, or `before` (`STORAGE_INVALID_FILTER`) — or the sort
+            is unsupported (`STORAGE_INVALID_SORT`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                pagingField:
+                  summary: pageSize sent in the body
+                  value:
+                    errors:
+                      - code: STORAGE_INVALID_FILTER
+                        message: pageSize is not supported for export
   /v1/storage/usage:
     get:
       x-internal: false
@@ -3366,6 +3734,391 @@ components:
               description: Name of the item at the time of deletion.
               examples:
                 - old-report.pdf
+    StorageActivityEntry:
+      type: object
+      description: |-
+        One action recorded against Celigo Storage in the environment. Every
+        file and folder change, download, recycle-bin step, storage query, and
+        file-server login writes one entry.
+      required:
+        - _id
+        - time
+        - _userId
+        - _byUserId
+        - byUserName
+        - source
+        - ip
+        - action
+        - _resourceId
+        - resourceName
+        - status
+        - type
+        - _integrationId
+        - details
+      properties:
+        _id:
+          type: string
+          format: uuid
+          description: |-
+            Unique identifier for this entry. Also the tiebreaker of the
+            `time` sort order.
+          examples:
+            - 01a1805c-a3ac-7dff-8766-9ee68c7aa5f0
+        time:
+          type: string
+          format: date-time
+          description: Timestamp when the action happened, in UTC with milliseconds.
+          examples:
+            - '2026-10-22T16:52:10.413Z'
+        _userId:
+          type: string
+          format: objectId
+          x-celigo-refModel: users
+          description: Environment owner the entry belongs to.
+          examples:
+            - 624cb0346309dc3a543733a2
+        _byUserId:
+          type: string
+          description: |-
+            Who performed the action: a user ID, or the file server account ID
+            when `source` is `fileserver`. Actions the platform takes for a user,
+            such as creating or removing an integration's root folder along with
+            the integration, carry that user's ID with `source` set to `system`.
+          examples:
+            - 624cb0346309dc3a543733a2
+        byUserName:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Display name of the actor: the user's name, or the SFTP username of a
+            file server account. Null when the actor no longer exists, as for a
+            deleted file server account.
+          examples:
+            - Jane Doe
+        source:
+          type: string
+          enum:
+            - ui
+            - api
+            - cli
+            - mcp
+            - ora
+            - connector
+            - script
+            - stack
+            - sso
+            - fileserver
+            - system
+          x-enumDescriptions:
+            ui: Action taken in the Celigo UI
+            api: Action taken through the REST API with an API token
+            cli: Action taken through the Celigo CLI
+            mcp: Action taken by an MCP server tool on the user's behalf
+            ora: Action taken by the Ora AI agent
+            connector: Action taken by an integration app
+            script: Action taken by a script or hook
+            stack: Action taken by stack code
+            sso: Action taken in a single sign-on session
+            fileserver: Action taken over SFTP through the Celigo file server, including logins
+            system: Action taken by an automated platform process
+          description: How the action was initiated.
+          examples:
+            - api
+        ip:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Client IP address the action came from; for `fileserver` entries, the
+            SFTP partner's address. Null when the platform did not receive one,
+            as for `system` actions.
+          examples:
+            - 203.0.113.24
+        action:
+          type: string
+          enum:
+            - create
+            - upload
+            - update
+            - download
+            - move
+            - copy
+            - merge
+            - delete
+            - restore
+            - purge
+            - query
+            - login
+            - preview
+          x-enumDescriptions:
+            create: A folder was created
+            upload: A file's bytes finished uploading, including a replace of an existing file
+            update: A file or folder was renamed or had its description changed
+            download: A download URL was issued for a file, or a zip was built for a folder
+            move: An item moved to another folder, renamed in the same request when a new name was given
+            copy: A file was copied; the entry belongs to the new copy
+            merge: A folder was merged into another folder; the entry belongs to the destination folder
+            delete: An item went to the recycle bin
+            restore: An item came back from the recycle bin
+            purge: An item was permanently removed from the recycle bin
+            query: A storage SQL query read files; the entry carries no item
+            login: A file server account signed in over SFTP, or failed to; the entry carries no item
+            preview: Reserved; accepted as a filter value
+          description: |-
+            What happened. A file's history starts with `upload`, or with `copy`
+            for a copy, and a folder's with `create`; `update`, `download`, and
+            `move` entries follow while the item is live, and `delete` is followed
+            by `restore` or `purge`.
+          examples:
+            - update
+        _resourceId:
+          type: string
+          description: |-
+            File or folder the action applied to, as an ObjectId string. Empty
+            for `query` and `login` entries, which belong to no item. Use with
+            the `_resourceId` filter to read one item's history.
+          examples:
+            - 683b2a0e1c3d5f001a9e8b01
+        resourceName:
+          type:
+            - string
+            - 'null'
+          description: |-
+            Current name of the item, read at request time, so a renamed item
+            shows its latest name. Null when the item has been purged or the
+            entry has no item.
+          examples:
+            - quarterly-report.pdf
+        status:
+          type:
+            - string
+            - 'null'
+          enum:
+            - active
+            - deleted
+            - null
+          x-enumDescriptions:
+            active: The item is live
+            deleted: The item is in the recycle bin
+          description: |-
+            Current state of the item, read at request time. Null when the
+            item has been purged or the entry has no item.
+          examples:
+            - active
+        type:
+          type:
+            - string
+            - 'null'
+          enum:
+            - file
+            - folder
+            - null
+          x-enumDescriptions:
+            file: The entry belongs to a file
+            folder: The entry belongs to a folder
+          description: Type of the item. Null for `query` and `login` entries.
+          examples:
+            - file
+        _integrationId:
+          type:
+            - string
+            - 'null'
+          format: objectId
+          x-celigo-refModel: integrations
+          description: |-
+            Integration whose system folder tree holds the item. Null for items
+            outside any integration and for `query` and `login` entries.
+          examples:
+            - null
+        details:
+          type: object
+          additionalProperties: true
+          description: |-
+            Action-specific facts, an empty object when there are none, as for a
+            `merge` or a folder's `purge`. `create` and `restore` carry the parent
+            folder (`_parentId`); `move` carries `_previousParentId` and
+            `_newParentId`, plus `previousName` and `newName` when it also renamed
+            the item and `bulk` when it came from `POST /v1/storage/items/move`.
+            Renames carry `previousName` and `newName`, and description edits
+            `previousDescription` and `newDescription`. `upload` carries `bytes`
+            and `overwrite`, plus `previousBytes` when it replaced content;
+            `download` carries `size` and `linkExpiresIn`, plus `fileCount` for a
+            folder; `copy` carries `_sourceId`, `_destinationParentId`, and
+            `bytes`; `delete` carries the item's `name`; a file's `purge` carries
+            `bytes`; `query` carries the `sql`; `login` carries `method`,
+            `success`, and, on a failure, `reason`.
+          examples:
+            - previousName: report.pdf
+              newName: quarterly-report.pdf
+    StorageActivityFilters:
+      type: object
+      description: |-
+        Filters for the activity export: the same names, values, and rules as
+        the filter and sort parameters of `GET /v1/storage/activity`. Every
+        filter is optional and they combine with AND; the paging parameters
+        (`pageSize`, `limit`, `after`, `before`) are rejected.
+      properties:
+        _resourceId:
+          type: string
+          format: objectId
+          x-celigo-refModel: storageitems
+          description: |-
+            Export only this item's history, including entries recorded after it
+            went to the recycle bin.
+          examples:
+            - 683b2a0e1c3d5f001a9e8b01
+        _byUserId:
+          type: array
+          maxItems: 50
+          description: |-
+            Export only entries by these actors: user IDs, file server account
+            IDs, or `system`. A comma-separated string is also accepted.
+          items:
+            type: string
+            pattern: ^([0-9a-fA-F]{24}|system)$
+          examples:
+            - - 624cb0346309dc3a543733a2
+              - system
+        source:
+          type: array
+          maxItems: 50
+          description: Export only entries initiated through these channels.
+          items:
+            type: string
+            enum:
+              - ui
+              - api
+              - cli
+              - mcp
+              - ora
+              - connector
+              - script
+              - stack
+              - sso
+              - fileserver
+              - system
+            x-enumDescriptions:
+              ui: Celigo UI
+              api: REST API
+              cli: Celigo CLI
+              mcp: MCP server tools
+              ora: Ora AI agent
+              connector: Integration apps
+              script: Scripts and hooks
+              stack: Stack code
+              sso: Single sign-on sessions
+              fileserver: SFTP through the Celigo file server
+              system: Automated platform processes
+          examples:
+            - - ui
+              - api
+        action:
+          type: array
+          maxItems: 50
+          description: Export only entries for these actions.
+          items:
+            type: string
+            enum:
+              - create
+              - upload
+              - update
+              - download
+              - move
+              - copy
+              - merge
+              - delete
+              - restore
+              - purge
+              - query
+              - login
+              - preview
+            x-enumDescriptions:
+              create: Folder created
+              upload: File uploaded or replaced
+              update: Item renamed or re-described
+              download: Download issued
+              move: Item moved
+              copy: File copied
+              merge: Folder merged
+              delete: Item sent to the recycle bin
+              restore: Item restored
+              purge: Item permanently removed
+              query: Storage SQL query
+              login: File server login
+              preview: Reserved
+          examples:
+            - - delete
+              - purge
+        time_gte:
+          type: string
+          description: Export only entries at or after this time. ISO 8601 or epoch milliseconds.
+          examples:
+            - '2026-10-01T00:00:00.000Z'
+        time_lte:
+          type: string
+          description: |-
+            Export only entries at or before this time. ISO 8601 or epoch
+            milliseconds; must not be earlier than `time_gte`.
+          examples:
+            - '2026-10-31T23:59:59.999Z'
+        sort_by:
+          type: string
+          enum:
+            - time
+          default: time
+          x-enumDescriptions:
+            time: Order rows by when the action happened
+          description: Field the CSV rows are ordered by. Only `time` is supported.
+          examples:
+            - time
+        sort_order:
+          type: string
+          enum:
+            - asc
+            - desc
+          default: desc
+          x-enumDescriptions:
+            asc: Oldest entry first
+            desc: Newest entry first
+          description: Row order of the CSV by `time`. The default puts the newest entry on the first row.
+          examples:
+            - desc
+    StorageActivityExport:
+      type: object
+      description: A presigned link to the CSV export and how much of the log it holds.
+      required:
+        - downloadUrl
+        - expiresIn
+        - rowCount
+        - hasMore
+      properties:
+        downloadUrl:
+          type: string
+          format: uri
+          description: |-
+            Presigned S3 URL to GET the CSV from, served as an attachment named
+            `storage-activity-<UTC timestamp>.csv`. Columns are Time, Source,
+            User, Resource, Name/ID, Action, IP, and Details; times are UTC.
+          examples:
+            - https://integrator-userdata-delete-30.s3.us-east-1.amazonaws.com/file-storage-activity-results/624cb0346309dc3a543733a2/1793155211624-d765038e.csv?X-Amz-Expires=3600&X-Amz-Signature=REDACTED
+        expiresIn:
+          type: integer
+          description: Seconds the URL stays valid from the time of this response.
+          examples:
+            - 3600
+        rowCount:
+          type: integer
+          description: Number of entries written to the CSV, not counting the header row.
+          examples:
+            - 1250
+        hasMore:
+          type: boolean
+          description: |-
+            When true, more entries matched than the export wrote. Narrow
+            `time_gte`/`time_lte` and export again to get the rest.
+          examples:
+            - false
     Usage:
       type: object
       description: Account-wide storage usage and entitlement, aggregated across all environments.