@celigo/api-specs 0.2.201 → 0.2.203

package/dist/filestorage.yml

@@ -34,7 +34,9 @@ paths:
         `partUrls`, and `completeUrl` for larger files. Upload the bytes directly
         to those URLs — a single PUT must carry the
         `x-amz-server-side-encryption: AES256` header — then the item flips to
-        active once S3 confirms it; no further API call is needed. Each URL's
+        active once S3 confirms it; no further API call is needed. If the
+        uploaded object is empty (0 bytes), the file is not activated: it is
+        deleted permanently, without passing through the recycle bin. Each URL's
         lifetime is in its `X-Amz-Expires` parameter; once every part already
         issued has been uploaded, a multipart upload fetches further part URLs by
         posting again with the item's `_id`, `uploadId`, and `issuedPartsCount`,
@@ -222,7 +224,12 @@ paths:
                   downloadUrl:
                     type: string
                     format: uri
-                    description: Presigned S3 URL to GET the file's bytes from.
+                    description: |-
+                      Presigned S3 URL to GET the file's bytes from. The bytes are
+                      served as an attachment named after the item: the
+                      `Content-Disposition` header carries an ASCII `filename` in
+                      which non-ASCII characters are replaced with `_`, plus
+                      `filename*=UTF-8''` with the full name percent-encoded.
                     examples:
                       - https://integrator-file-storage.s3.us-west-2.amazonaws.com/file-storage/...
                   expiresIn:
@@ -611,6 +618,17 @@ paths:
                           description: Folder name.
                           examples:
                             - My Files
+                        _integrationId:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: integrations
+                          description: |-
+                            Integration whose system folder tree contains the listed
+                            folder. Present only on the last entry (the listed folder
+                            itself), and only when that folder is the integration's
+                            root folder or inside it.
+                          examples:
+                            - 6ab1e7ab38d7733b4594d0d2
               examples:
                 listMode:
                   summary: List a folder's children
@@ -839,7 +857,10 @@ paths:
 
         Only files are looked up: a folder's id is treated as unknown, so it
         fails the request or comes back as a `notFound` entry. Read folder
-        metadata from `GET /v1/storage/items`.
+        metadata from `GET /v1/storage/items`. A pending file is returned, as
+        active, once its bytes have landed in storage, even if the upload has not
+        finalized yet; a pending file whose bytes have not been uploaded is
+        treated as unknown.
       operationId: batchGetStorageItems
       tags:
         - File Storage
@@ -1293,9 +1314,12 @@ paths:
         Updates an item's `name` and/or `description`. Renaming keeps the item's
         `_id` stable, so references from flows, exports, imports, and tokens
         survive; a name already held by another live item in the same folder is
-        rejected with 409 `STORAGE_ITEM_ALREADY_EXISTS`. To move an item to a
-        different folder, use `PATCH /v1/storage/items/{_id}/move`; to replace a
-        file's content, use `PATCH /v1/storage/items/{_id}/replace`.
+        rejected with 409 `STORAGE_ITEM_ALREADY_EXISTS`. An integration's root
+        folder (`isSystem`) can be renamed and described too; renaming the
+        integration updates only the folder's `integrationName`, never its
+        `name`. To move an item to a different folder, use
+        `PATCH /v1/storage/items/{_id}/move`; to replace a file's content, use
+        `PATCH /v1/storage/items/{_id}/replace`.
       operationId: updateStorageItem
       tags:
         - File Storage
@@ -1450,7 +1474,9 @@ paths:
         placement are preserved, so every reference to the file stays intact — use
         this instead of delete-and-recreate when a file is referenced by flows or
         exports. The previous content remains downloadable until the replacement
-        finalizes. Rename with `PUT /v1/storage/items/{_id}` instead; this
+        finalizes. Uploading empty (0-byte) content does not replace it: the file
+        itself is deleted permanently, without passing through the recycle bin.
+        Rename with `PUT /v1/storage/items/{_id}` instead; this
         endpoint does not accept a name.
       operationId: replaceStorageFileContent
       tags:
@@ -1565,7 +1591,13 @@ paths:
         file: the destination file keeps its `_id` and takes the source file's
         content, its previous content is discarded, and the source file's `_id`
         is removed — neither goes to the recycle bin, so references to the
-        source file break. A soft-deleted source folder may be
+        source file break. A sub-folder whose name the destination also holds as
+        a folder is merged into it the same way. When the names match but the
+        types differ (a file against a folder), both are kept: the destination
+        item is unchanged, and the source item moves in with its `_id` under the
+        first free `<name> (k)` — the suffix follows the full name, so
+        `report.pdf` lands as `report.pdf (1)`, or `report.pdf (2)` when
+        `report.pdf (1)` is taken. A soft-deleted source folder may be
         merged, which restores its contents into the destination. Folders only —
         move individual files with the move endpoint. Requires delete access on
         the source folder and write access on the destination.
@@ -2279,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
@@ -2425,7 +2825,7 @@ components:
         size:
           type: integer
           format: int64
-          minimum: 0
+          minimum: 1
           description: |-
             Declared size in bytes. Used to reserve quota up front. When omitted,
             the backend reserves a worst-case estimate (1 GB for single,
@@ -2765,6 +3165,18 @@ components:
             integration purges them.
           examples:
             - 6ab1e7ab38d7733b4594d0d2
+        _fileServerAccountId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: fileserveraccounts
+          description: |-
+            File Server account that uploaded the file over SFTP, or that most
+            recently replaced its content over SFTP. Absent for folders and for
+            files uploaded through this API; replacing the content through this
+            API keeps the current value.
+          examples:
+            - 6ac0f3e1b2d4a5001c7e9f10
         integrationName:
           type: string
           readOnly: true
@@ -2772,6 +3184,9 @@ components:
             Name of the integration an integration root folder belongs to. Present
             only on that root folder (the `isSystem` folder at the account root);
             items inside the tree carry `_integrationId` but not this field.
+            Follows the integration's name when the integration is renamed, while
+            the folder's own `name` keeps the value it was created with or last
+            renamed to, so the two can differ.
           examples:
             - Order to cash
         __ancestorIds:
@@ -2802,10 +3217,15 @@ components:
           maxLength: 256
           readOnly: true
           description: |-
-            Media type recorded at upload time, used to set the download
-            Content-Type. Present when type is file; absent for folders and for
-            files uploaded without a declared type. Matched case-sensitively by
-            the `mimeType` and `mimeType_nin` list filters.
+            Media type used to set the download Content-Type. Present when type is
+            file; absent for folders and for files uploaded through this API
+            without a declared type. A file uploaded over the SFTP file server gets
+            the type its name's extension maps to, ignoring a trailing `.filepart`,
+            `.part`, or `.tmp`, or `application/octet-stream` when the extension is
+            unknown. An SFTP rename replaces an absent or `application/octet-stream`
+            value when the new extension maps to a known type; renames made with an
+            API token leave the value unchanged. Matched case-sensitively by the
+            `mimeType` and `mimeType_nin` list filters.
           examples:
             - image/png
         description:
@@ -2831,11 +3251,13 @@ components:
           type: boolean
           readOnly: true
           description: |-
-            When true, the platform created the item (for example a system or
-            integration folder) and protects it — rename, move, content replace,
-            copy, delete, and purge are rejected with 403
-            `STORAGE_SYSTEM_ITEM_PROTECTED` ("System items cannot be modified or
-            deleted").
+            When true, the platform created the item (for example an
+            integration's root folder) and protects it: moving it, merging it
+            into another folder, deleting it, and restoring or purging it from
+            the recycle bin are rejected with 403 `STORAGE_SYSTEM_ITEM_PROTECTED`
+            ("System items cannot be modified or deleted"; a per-item error in a
+            bulk move). Renaming it and editing its description with
+            `PUT /v1/storage/items/{_id}` are allowed.
         deletedAt:
           type: string
           format: date-time
@@ -3049,7 +3471,7 @@ components:
         size:
           type: integer
           format: int64
-          minimum: 0
+          minimum: 1
           description: |-
             Declared size in bytes of the replacement content, used to reserve
             quota. Reconciled to the real size when the upload finalizes.
@@ -3312,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.