@celigo/api-specs 0.2.39 → 0.2.40

package/dist/filestorage.yml

@@ -32,8 +32,10 @@ paths:
         pending item, and returns presigned S3 URLs to transfer the bytes to:
         a single PUT URL for files up to 5 GB, or a multipart `uploadId`,
         `partUrls`, and `completeUrl` for larger files. Upload the bytes directly
-        to those URLs, then the item flips to active once S3 confirms it — no
-        further API call is needed. URLs expire after one hour; reissue them with
+        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
+        lifetime is in its `X-Amz-Expires` parameter; reissue expired URLs with
         `POST /v1/storage/files/refresh-urls`. Each file is validated
         independently, so the response can mix per-file successes and failures
         while the request itself returns 200.
@@ -126,10 +128,10 @@ paths:
       summary: Refresh upload URLs
       description: |-
         Reissues presigned upload URLs for pending uploads whose URLs have
-        expired (URLs last one hour). For a single PUT, returns a fresh upload
-        URL; for multipart, returns fresh URLs for the requested part numbers plus
-        the complete URL. Already-uploaded parts are preserved. Each item is
-        processed independently.
+        expired (each URL's lifetime is in its `X-Amz-Expires` parameter). For a
+        single PUT, returns a fresh upload URL; for multipart, returns fresh URLs
+        for the requested part numbers plus the complete URL. Already-uploaded
+        parts are preserved. Each item is processed independently.
       operationId: refreshStorageUploadUrls
       tags:
         - File Storage
@@ -275,6 +277,115 @@ paths:
           $ref: '#/components/responses/404-not-found'
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/storage/folders/{_id}/download:
+    get:
+      x-internal: false
+      summary: Get a folder download URL
+      description: |-
+        Packages a folder and everything beneath it into a zip and returns a
+        short-lived presigned S3 URL to fetch it from — the content does not pass
+        through this API. The zip is built synchronously before the response, so
+        large trees take longer to answer; entries are rooted at the folder's own
+        name and every subfolder is written as a directory entry, so empty
+        subfolders survive extraction. Pending (not yet finalized) files are
+        skipped. Re-downloading the same folder overwrites its previously staged
+        zip rather than piling up copies. Folders only; download a single file
+        with `GET /v1/storage/files/{_id}/download`.
+      operationId: getStorageFolderDownloadUrl
+      tags:
+        - File Storage
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: ID of the folder to download.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+            examples:
+              - 684c3b1f2d4e6a002b0f9c34
+      responses:
+        '200':
+          description: A presigned download URL for the zip, its lifetime, and what it contains.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - downloadUrl
+                  - expiresIn
+                  - name
+                  - fileCount
+                  - size
+                properties:
+                  downloadUrl:
+                    type: string
+                    format: uri
+                    description: |-
+                      Presigned S3 URL to GET the zip from. Serves the archive with
+                      a `Content-Disposition: attachment` header carrying `name`.
+                    examples:
+                      - https://integrator-file-storage.s3.us-west-2.amazonaws.com/file-storage/.../folder-downloads/684c3b1f2d4e6a002b0f9c34.zip?X-Amz-Expires=3600&...
+                  expiresIn:
+                    type: integer
+                    description: Seconds the URL stays valid from the time of this response.
+                    examples:
+                      - 3600
+                  name:
+                    type: string
+                    description: |-
+                      File name of the zip — the folder's name with characters that
+                      are illegal in file names replaced by `_`, plus `.zip`.
+                    examples:
+                      - Reports.zip
+                  fileCount:
+                    type: integer
+                    description: Number of files packaged into the zip. Folders are not counted.
+                    examples:
+                      - 3
+                  size:
+                    type: integer
+                    format: int64
+                    description: Total uncompressed size in bytes of the packaged files.
+                    examples:
+                      - 51
+              examples:
+                default:
+                  value:
+                    downloadUrl: https://integrator-file-storage.s3.us-west-2.amazonaws.com/file-storage/624cb0346309dc3a543733a2/folder-downloads/684c3b1f2d4e6a002b0f9c34.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3B%20filename%3D%22Reports.zip%22&X-Amz-Signature=REDACTED
+                    expiresIn: 3600
+                    name: Reports.zip
+                    fileCount: 3
+                    size: 51
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          description: No folder or file with this ID exists in the environment. Error code `STORAGE_ITEM_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notFound:
+                  value:
+                    errors:
+                      - code: STORAGE_ITEM_NOT_FOUND
+                        message: Storage item not found
+        '422':
+          description: The ID belongs to a file, not a folder. Error code `STORAGE_NOT_A_FOLDER`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                notAFolder:
+                  value:
+                    errors:
+                      - code: STORAGE_NOT_A_FOLDER
+                        message: Storage item "orders.csv" is not a folder
   /v1/storage/items:
     get:
       x-internal: false
@@ -306,15 +417,59 @@ paths:
           in: query
           required: false
           description: |-
-            Recursive, case-insensitive substring match on item names across the
-            whole account. Switches the endpoint to search mode, where
-            `_parentId` is ignored and each item carries its `location`. Matches
-            names only, not contents or descriptions.
+            Recursive, case-insensitive match on item names across the whole
+            account. Switches the endpoint to search mode, where `_parentId` is
+            ignored and each item carries its `location`. Matches names only, not
+            contents or descriptions; a query of several words matches names that
+            contain any of them. Cannot be combined with `name`, `prefix`, or
+            `_integrationId`.
           schema:
             type: string
             minLength: 2
             examples:
               - report
+        - name: name
+          in: query
+          required: false
+          description: |-
+            Return only items whose name equals one of the given values —
+            case-sensitive, exact match. Repeat the parameter for several names;
+            a comma inside a value is part of the name, not a separator. Cannot
+            be combined with `search` or `prefix`.
+          schema:
+            type: array
+            items:
+              type: string
+              maxLength: 256
+            examples:
+              - - orders.csv
+                - invoices.csv
+        - name: prefix
+          in: query
+          required: false
+          description: |-
+            Return only items whose name starts with this value (case-sensitive).
+            A single value — cannot be combined with `search` or `name`.
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 256
+            examples:
+              - orders-2026-
+        - name: _integrationId
+          in: query
+          required: false
+          description: |-
+            Return only items that belong to this integration's system folder
+            tree. At the account root this yields the integration's root folder;
+            with `_parentId` set to a folder inside the tree it narrows that
+            folder's children. Cannot be combined with `search`.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: integrations
+            examples:
+              - 6ab1e7ab38d7733b4594d0d2
         - name: type
           in: query
           required: false
@@ -332,11 +487,36 @@ paths:
         - name: mimeType
           in: query
           required: false
-          description: Restrict results to files of a single media type.
+          description: |-
+            Return only files whose media type is one of the given values —
+            case-sensitive, exact match, so `image/*` is rejected. Pass several
+            values as a comma-separated list or by repeating the parameter; up to
+            50 distinct values per request. Folders never match.
           schema:
-            type: string
+            type: array
+            items:
+              type: string
+            maxItems: 50
             examples:
-              - image/png
+              - - text/csv
+                - image/png
+        - name: mimeType_nin
+          in: query
+          required: false
+          description: |-
+            Exclude files whose media type is one of the given values — the
+            "Other" filter. Same list syntax and 50-value cap as `mimeType`.
+            Folders carry no media type, so they are never excluded; add
+            `type=file` to drop them. Combined with `mimeType`, both conditions
+            apply.
+          schema:
+            type: array
+            items:
+              type: string
+            maxItems: 50
+            examples:
+              - - text/csv
+                - application/pdf
         - name: sort_by
           in: query
           required: false
@@ -467,13 +647,24 @@ paths:
                   value:
                     items:
                       - _id: 684c3b1f2d4e6g002b0h9c34
+                        _userId: 624cb0346309dc3a543733a2
+                        _parentId: 683a1f2e9b0c4d001e8f7a23
+                        __ancestorIds:
+                          - 683a1f2e9b0c4d001e8f7a23
+                        _integrationId: null
                         type: folder
                         name: Reports
+                        size: 0
                         status: active
                         isSystem: false
                         createdAt: '2026-03-28T10:00:00.000Z'
                         lastModified: '2026-03-28T14:30:00.000Z'
                       - _id: 683b2a0e1c3d5f001a9e8b01
+                        _userId: 624cb0346309dc3a543733a2
+                        _parentId: 683a1f2e9b0c4d001e8f7a23
+                        __ancestorIds:
+                          - 683a1f2e9b0c4d001e8f7a23
+                        _integrationId: null
                         type: file
                         name: logo.png
                         size: 245760
@@ -485,11 +676,33 @@ paths:
                     breadcrumb:
                       - _id: 683a1f2e9b0c4d001e8f7a23
                         name: My Files
+                integrationRoot:
+                  summary: Account root listing showing an integration's system folder
+                  value:
+                    items:
+                      - _id: 6ab1e7abaa3e7ed226ea3cc4
+                        _userId: 624cb0346309dc3a543733a2
+                        _parentId: null
+                        __ancestorIds: []
+                        _integrationId: 6ab1e7ab38d7733b4594d0d2
+                        integrationName: Order to cash
+                        type: folder
+                        name: Order to cash
+                        size: 0
+                        status: active
+                        isSystem: true
+                        createdAt: '2026-09-10T08:12:41.000Z'
+                        lastModified: '2026-09-10T08:12:41.000Z'
                 searchMode:
                   summary: Search by name
                   value:
                     items:
                       - _id: 683b2a0e1c3d5f001a9e8b01
+                        _userId: 624cb0346309dc3a543733a2
+                        _parentId: 683a1f2e9b0c4d001e8f7a23
+                        __ancestorIds:
+                          - 683a1f2e9b0c4d001e8f7a23
+                        _integrationId: null
                         type: file
                         name: logo.png
                         size: 245760
@@ -510,7 +723,32 @@ paths:
         '404':
           $ref: '#/components/responses/404-not-found'
         '422':
-          $ref: '#/components/responses/422-unprocessable-entity'
+          description: |-
+            A filter is malformed or two filters that cannot be combined were
+            sent together. Error code: `STORAGE_INVALID_FILTER`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidMimeType:
+                  summary: Media type is not a valid type/subtype pair
+                  value:
+                    errors:
+                      - code: STORAGE_INVALID_FILTER
+                        message: 'Invalid MIME type format in mimeType: image/*'
+                tooManyMimeTypes:
+                  summary: More than 50 values in one media-type filter
+                  value:
+                    errors:
+                      - code: STORAGE_INVALID_FILTER
+                        message: mimeType must not exceed 50 entries
+                exclusiveFilters:
+                  summary: prefix sent together with search
+                  value:
+                    errors:
+                      - code: STORAGE_INVALID_FILTER
+                        message: prefix and search are mutually exclusive
     post:
       x-internal: false
       summary: Create a folder
@@ -549,8 +787,14 @@ paths:
                 default:
                   value:
                     _id: 684c3b1f2d4e6g002b0h9c34
+                    _userId: 624cb0346309dc3a543733a2
+                    _parentId: 683a1f2e9b0c4d001e8f7a23
+                    __ancestorIds:
+                      - 683a1f2e9b0c4d001e8f7a23
+                    _integrationId: null
                     type: folder
                     name: Reports
+                    size: 0
                     description: Quarterly financial reports
                     status: active
                     isSystem: false
@@ -973,6 +1217,10 @@ paths:
                   value:
                     items:
                       - _id: 683b2a0e1c3d5f001a9e8b01
+                        _userId: 60a1b2c3d4e5f6001a2b3c4d
+                        _parentId: null
+                        __ancestorIds: []
+                        _integrationId: null
                         type: file
                         name: old-report.pdf
                         size: 245760
@@ -984,8 +1232,13 @@ paths:
                         createdAt: '2026-03-01T09:00:00.000Z'
                         lastModified: '2026-03-28T10:00:00.000Z'
                       - _id: 684c3b1f2d4e6g002b0h9c34
+                        _userId: 60a1b2c3d4e5f6001a2b3c4d
+                        _parentId: null
+                        __ancestorIds: []
+                        _integrationId: null
                         type: folder
                         name: Archived Reports
+                        size: 0
                         status: active
                         isSystem: false
                         deletedBy: 60a1b2c3d4e5f6001a2b3c4d
@@ -1059,6 +1312,11 @@ paths:
                 default:
                   value:
                     _id: 683b2a0e1c3d5f001a9e8b01
+                    _userId: 624cb0346309dc3a543733a2
+                    _parentId: 683a1f2e9b0c4d001e8f7a23
+                    __ancestorIds:
+                      - 683a1f2e9b0c4d001e8f7a23
+                    _integrationId: null
                     type: file
                     name: quarterly-report-final.pdf
                     description: Updated Q1 2026 financial report
@@ -1088,9 +1346,8 @@ paths:
         its entire subtree; the folder is removed immediately and its descendants
         follow asynchronously. Delete is never blocked by references — flows,
         exports, imports, and tokens that point at the item are left dangling and
-        fail at runtime, so check `GET /v1/storage/items/{_id}/dependencies`
-        first. A pending multipart upload cannot be deleted here — cancel it with
-        `POST /v1/storage/files/{_id}/cancel`.
+        fail at runtime. A pending multipart upload cannot be deleted here —
+        cancel it with `POST /v1/storage/files/{_id}/cancel`.
       operationId: deleteStorageItem
       tags:
         - File Storage
@@ -1506,9 +1763,13 @@ paths:
                 default:
                   value:
                     _id: 685d4c2g3e5f7h003c1i0d45
+                    _userId: 624cb0346309dc3a543733a2
+                    _parentId: 684c3b1f2d4e6g002b0h9c34
+                    __ancestorIds:
+                      - 684c3b1f2d4e6g002b0h9c34
+                    _integrationId: null
                     type: file
                     name: quarterly-report-copy.pdf
-                    _parentId: 684c3b1f2d4e6g002b0h9c34
                     size: 5242880
                     mimeType: application/pdf
                     description: Q1 2026 financial report
@@ -1602,169 +1863,156 @@ paths:
           $ref: '#/components/responses/404-not-found'
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
-  /v1/storage/items/{_id}/dependencies:
+  /v1/files/{_id}/audit:
     get:
       x-internal: false
-      operationId: listStorageItemDependencies
+      summary: Get audit log for a file
+      description: |-
+        Returns the change history for a file — creation (recorded once the
+        upload finalizes), renames and description edits, moves, content
+        replacements, downloads, deletes, restores, and purges — newest first.
+        Each entry records who made the change, when, and which fields were
+        affected. History survives purging, so a purged file's entries stay
+        readable. Folders have their own route, `GET /v1/folders/{_id}/audit`.
       tags:
         - File Storage
-      summary: List dependencies of an item
-      description: |-
-        Returns the resources that reference this item — flows, exports, imports,
-        MCP servers, and access tokens. These references are soft: they never
-        block a delete or move, and go dangling if the item is removed. Check this
-        before deleting or moving an item to see what may break.
+      operationId: getStorageFileAudit
       parameters:
         - name: _id
           in: path
+          description: File ID.
           required: true
-          description: Item ID.
           schema:
             type: string
             format: objectId
             x-celigo-refModel: storageitems
             examples:
               - 683b2a0e1c3d5f001a9e8b01
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/After'
+        - $ref: '#/components/parameters/From'
+        - $ref: '#/components/parameters/To'
+        - $ref: '#/components/parameters/Action'
+        - $ref: '#/components/parameters/Source'
+        - $ref: '#/components/parameters/ByUserId'
       responses:
         '200':
-          description: |-
-            Dependency map. Keys are resource-type strings; values are arrays of
-            dependency entries. Returns `{}` when nothing references the item.
+          description: Array of audit entries, newest first.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination link. Includes `<...>; rel="next"` with an
+                `after` cursor when more entries exist; absent on the final page.
+              schema:
+                type: string
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/DependencyResponse'
+                type: array
+                items:
+                  $ref: '#/components/schemas/StorageAuditEntry'
               examples:
-                withDependents:
-                  summary: Item referenced by a flow
+                default:
+                  summary: A file that was renamed after upload
                   value:
-                    flows:
-                      - id: 673e486ac12b3453ea0ba99a
-                        name: Nightly export
-                        paths:
-                          - pageGenerators[*]._exportId
-                        accessLevel: manage
-                        dependencyIds:
-                          export:
-                            - 673e486adc497ab5e649f1ca
-                empty:
-                  summary: No dependents
-                  value: {}
+                    - _id: 69f63dd77009ea11abf0bce3
+                      resourceType: file
+                      _resourceId: 683b2a0e1c3d5f001a9e8b01
+                      source: api
+                      event: update
+                      time: '2026-05-02T18:09:26.975Z'
+                      byUser:
+                        _id: 624cb0346309dc3a543733a2
+                        email: user@example.com
+                        name: Jane Doe
+                      fieldChanges:
+                        - fieldPath: name
+                          oldValue: report.pdf
+                          newValue: quarterly-report.pdf
+                    - _id: 6ab1f69bf9f97c6e8f353b3c
+                      resourceType: file
+                      _resourceId: 683b2a0e1c3d5f001a9e8b01
+                      source: ui
+                      event: create
+                      time: '2026-05-02T17:58:39.755Z'
+                      fieldChanges: []
+                      byUser:
+                        _id: 624cb0346309dc3a543733a2
+                        email: user@example.com
+                        name: Jane Doe
+        '204':
+          description: No audit entries exist for this file ID.
+        '400':
+          description: The `_id` is not a valid ObjectId (`invalid_ref`), or `limit` is out of range (`invalid_query_param`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidId:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _id.
+                invalidLimit:
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: Invalid limit sent in request.
         '401':
           $ref: '#/components/responses/401-unauthorized'
-        '404':
-          $ref: '#/components/responses/404-not-found'
-  /v1/storageitems/{_id}/audit:
+        '422':
+          description: |-
+            A filter value is invalid — an unknown `action` or `source`
+            (`invalid_audit_field`), a `from`/`to` that is not ISO 8601
+            (`invalid_timestamp_format`), or a window outside the last three
+            years or in the future (`invalid_time_period`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidSource:
+                  value:
+                    errors:
+                      - code: invalid_audit_field
+                        message: bogus is not a valid audit source.
+                invalidTimePeriod:
+                  value:
+                    errors:
+                      - code: invalid_time_period
+                        message: 'Please make sure that the time provided for field: "to" is not older than 3 year(s) to current date and is not a future date.'
+  /v1/folders/{_id}/audit:
     get:
       x-internal: false
-      summary: Get audit log for an item
+      summary: Get audit log for a folder
       description: |-
-        Returns the change history for a storage item — creation, renames and
-        description edits, moves, content replacements, downloads, deletes,
-        restores, and purges — newest first. Each entry records who made the
-        change, when, and which fields were affected.
+        Returns the change history for a folder — creation, renames and
+        description edits, moves, deletes, restores, and purges — newest first.
+        Each entry records who made the change, when, and which fields were
+        affected. History survives purging, so a purged folder's entries stay
+        readable. Files have their own route, `GET /v1/files/{_id}/audit`.
       tags:
         - File Storage
-      operationId: getStorageItemAudit
+      operationId: getStorageFolderAudit
       parameters:
         - name: _id
           in: path
-          description: Item ID.
+          description: Folder ID.
           required: true
           schema:
             type: string
             format: objectId
             x-celigo-refModel: storageitems
             examples:
-              - 683b2a0e1c3d5f001a9e8b01
-        - 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-05-31T23:59:59.999Z'
-        - name: action
-          in: query
-          required: false
-          description: Filter by the change type. Maps to the `event` field on each entry.
-          schema:
-            type: string
-            enum:
-              - create
-              - update
-              - delete
-              - download
-              - restore
-              - purge
-            examples:
-              - update
-            x-enumDescriptions:
-              create: An item was created.
-              update: An item was renamed, re-described, moved, or had its content replaced.
-              delete: An item was soft-deleted to the recycle bin.
-              download: A presigned download URL was issued for a file.
-              restore: An item was restored from the recycle bin.
-              purge: An item was permanently purged from the recycle bin.
-        - name: source
-          in: query
-          required: false
-          description: Filter by how the change was initiated.
-          schema:
-            type: string
-            enum:
-              - ui
-              - api
-              - system
-            examples:
-              - ui
-            x-enumDescriptions:
-              ui: Change made through the Celigo web UI.
-              api: Change made via the REST API.
-              system: Change made automatically by the platform.
-        - name: _byUserId
-          in: query
-          required: false
-          description: Filter to changes performed by a single user.
-          schema:
-            type: string
-            format: objectId
-            x-celigo-refModel: users
-            examples:
-              - 624cb0346309dc3a543733a2
+              - 684c3b1f2d4e6a002b0f9c34
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/After'
+        - $ref: '#/components/parameters/From'
+        - $ref: '#/components/parameters/To'
+        - $ref: '#/components/parameters/Action'
+        - $ref: '#/components/parameters/Source'
+        - $ref: '#/components/parameters/ByUserId'
       responses:
         '200':
           description: Array of audit entries, newest first.
@@ -1780,133 +2028,77 @@ paths:
               schema:
                 type: array
                 items:
-                  type: object
-                  properties:
-                    _id:
-                      type: string
-                      format: objectId
-                      description: Unique identifier for this audit entry.
-                      examples:
-                        - 69f63dd77009ea11abf0bce3
-                    resourceType:
-                      type: string
-                      description: Always `storageitem` for this endpoint.
-                      examples:
-                        - storageitem
-                    _resourceId:
-                      type: string
-                      format: objectId
-                      x-celigo-refModel: storageitems
-                      description: ID of the item this entry belongs to.
-                      examples:
-                        - 683b2a0e1c3d5f001a9e8b01
-                    event:
-                      type: string
-                      description: Type of change that occurred.
-                      enum:
-                        - create
-                        - update
-                        - delete
-                        - download
-                        - restore
-                        - purge
-                      x-enumDescriptions:
-                        create: Item was created.
-                        update: Item was renamed, re-described, moved, or had its content replaced.
-                        delete: Item was soft-deleted to the recycle bin.
-                        download: A presigned download URL was issued for the file.
-                        restore: Item was restored from the recycle bin.
-                        purge: Item was permanently purged.
-                    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-05-02T18:09:26.975Z'
-                    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:
-                              - name
-                          oldValue:
-                            description: Previous value (absent on create).
-                          newValue:
-                            description: New value (absent on delete).
-                    deletedInfo:
-                      type: object
-                      description: Metadata about the deleted item. Present on `delete` events.
-                      properties:
-                        name:
-                          type: string
-                          description: Name of the item at the time of deletion.
-                          examples:
-                            - old-report.pdf
+                  $ref: '#/components/schemas/StorageAuditEntry'
               examples:
                 default:
+                  summary: A folder that was created and later deleted
                   value:
-                    - _id: 69f63dd77009ea11abf0bce3
-                      resourceType: storageitem
-                      _resourceId: 683b2a0e1c3d5f001a9e8b01
+                    - _id: 6ab1f736f9f97c6e8f353b5a
+                      resourceType: folder
+                      _resourceId: 684c3b1f2d4e6a002b0f9c34
                       source: api
-                      event: update
-                      time: '2026-05-02T18:09:26.975Z'
+                      event: delete
+                      time: '2026-09-22T03:34:13.999Z'
+                      fieldChanges: []
+                      deletedInfo:
+                        name: Reports
                       byUser:
                         _id: 624cb0346309dc3a543733a2
+                        name: Jane Doe
+                        email: user@example.com
+                    - _id: 6ab1f25df9f97c6e8f352d63
+                      resourceType: folder
+                      _resourceId: 684c3b1f2d4e6a002b0f9c34
+                      source: api
+                      event: create
+                      time: '2026-09-22T03:13:33.631Z'
+                      fieldChanges: []
+                      byUser:
+                        _id: 624cb0346309dc3a543733a2
+                        name: Jane Doe
                         email: user@example.com
-                        name: Tyler Lamparter
-                      fieldChanges:
-                        - fieldPath: name
-                          oldValue: report.pdf
-                          newValue: quarterly-report.pdf
         '204':
-          description: No audit entries exist for this item.
+          description: No audit entries exist for this folder ID.
         '400':
-          $ref: '#/components/responses/400-bad-request'
+          description: The `_id` is not a valid ObjectId (`invalid_ref`), or `limit` is out of range (`invalid_query_param`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidId:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _id.
+                invalidLimit:
+                  value:
+                    errors:
+                      - code: invalid_query_param
+                        message: Invalid limit sent in request.
         '401':
           $ref: '#/components/responses/401-unauthorized'
-        '404':
-          $ref: '#/components/responses/404-not-found'
         '422':
-          $ref: '#/components/responses/422-unprocessable-entity'
+          description: |-
+            A filter value is invalid — an unknown `action` or `source`
+            (`invalid_audit_field`), a `from`/`to` that is not ISO 8601
+            (`invalid_timestamp_format`), or a window outside the last three
+            years or in the future (`invalid_time_period`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalidAction:
+                  value:
+                    errors:
+                      - code: invalid_audit_field
+                        message: bogus is not a valid audit action.
+                invalidTimestamp:
+                  value:
+                    errors:
+                      - code: invalid_timestamp_format
+                        message: 'Please make sure that the time provided for field: "from" is in ISO8601 time format.'
   /v1/storage/usage:
     get:
       x-internal: false
@@ -2163,10 +2355,15 @@ components:
           format: uri
           description: |-
             Presigned S3 URL to PUT the file's bytes to in a single request.
-            Present when uploadType is single. Expires after one hour; use
-            `POST /v1/storage/files/refresh-urls` to reissue.
+            Present when uploadType is single. The PUT must carry the header
+            `x-amz-server-side-encryption: AES256` — it is part of the signature,
+            and S3 rejects the upload with 403 `SignatureDoesNotMatch` without
+            it. The URL's `X-Amz-Expires` parameter carries its lifetime; use
+            `POST /v1/storage/files/refresh-urls` to reissue an expired one.
           examples:
             - https://integrator-file-storage.s3.us-west-2.amazonaws.com/...
+          x-celigo-ai-guidance:
+            - Send the header x-amz-server-side-encryption AES256 on the presigned PUT; omitting it fails with 403 SignatureDoesNotMatch from S3, and the item then stays pending.
         uploadId:
           type: string
           description: |-
@@ -2394,6 +2591,14 @@ components:
             folder — the name is not a unique key.
           examples:
             - logo.png
+        _userId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: users
+          description: Environment user that owns the item; every item an account lists carries its own environment's value.
+          examples:
+            - 624cb0346309dc3a543733a2
         _parentId:
           type:
             - string
@@ -2406,6 +2611,30 @@ components:
             account root.
           examples:
             - 683a1f2e9b0c4d001e8f7a23
+        _integrationId:
+          type:
+            - string
+            - 'null'
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: integrations
+          description: |-
+            Integration whose system folder tree contains this item. Set on an
+            integration's root folder and inherited by everything created inside
+            it; null for user-created folders and files at the account root and
+            their descendants. Filter the list endpoint with `_integrationId` to
+            scope a listing to one integration.
+          examples:
+            - 6ab1e7ab38d7733b4594d0d2
+        integrationName:
+          type: string
+          readOnly: true
+          description: |-
+            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.
+          examples:
+            - Order to cash
         __ancestorIds:
           type: array
           readOnly: true
@@ -2424,9 +2653,9 @@ components:
           format: int64
           readOnly: true
           description: |-
-            File size in bytes. Present when type is file; folders carry no
-            size. While an upload is pending this reflects the reserved quota,
-            and is reconciled to the actual byte count once the upload finalizes.
+            File size in bytes; always `0` for folders, which hold no content.
+            While an upload is pending this reflects the reserved quota, and is
+            reconciled to the actual byte count once the upload finalizes.
           examples:
             - 245760
         mimeType:
@@ -2436,7 +2665,8 @@ components:
           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.
+            files uploaded without a declared type. Matched case-sensitively by
+            the `mimeType` and `mimeType_nin` list filters.
           examples:
             - image/png
         description:
@@ -2525,6 +2755,7 @@ components:
             - '2026-03-28T14:30:00.000Z'
       required:
         - _id
+        - _userId
         - type
         - name
         - status
@@ -2763,82 +2994,133 @@ components:
             with no name produces a second file with the same name.
           examples:
             - quarterly-report-copy.pdf
-    DependencyEntry:
+    StorageAuditEntry:
       type: object
-      description: A single resource that depends on the queried resource.
+      description: |-
+        One change recorded against a file or folder. Returned newest first by
+        `GET /v1/files/{_id}/audit` and `GET /v1/folders/{_id}/audit`.
+      required:
+        - _id
+        - resourceType
+        - _resourceId
+        - event
+        - source
+        - time
       properties:
-        id:
+        _id:
           type: string
-          description: Unique identifier of the dependent resource.
+          format: objectId
+          description: Unique identifier for this audit entry.
           examples:
-            - 61f92026dd053843b5d72350
-        name:
+            - 69f63dd77009ea11abf0bce3
+        resourceType:
           type: string
-          description: Display name of the dependent resource.
-          examples:
-            - Import Orders to NetSuite
-        paths:
-          type: array
+          enum:
+            - file
+            - folder
+          x-enumDescriptions:
+            file: The entry belongs to a file
+            folder: The entry belongs to a folder
           description: |-
-            Dot-notation paths within the dependent resource that reference
-            the target resource. `[*]` denotes array elements.
-          items:
-            type: string
+            Type of storage item the entry belongs to. Matches the route used —
+            `file` for `/v1/files/{_id}/audit`, `folder` for
+            `/v1/folders/{_id}/audit`.
           examples:
-            - - hooks.preSavePage._scriptId
-        accessLevel:
+            - folder
+        _resourceId:
+          type: string
+          format: objectId
+          x-celigo-refModel: storageitems
+          description: ID of the item this entry belongs to.
+          examples:
+            - 683b2a0e1c3d5f001a9e8b01
+        event:
           type: string
-          description: The caller's access level on the dependent resource.
+          enum:
+            - create
+            - update
+            - delete
+            - download
+            - restore
+            - purge
+          x-enumDescriptions:
+            create: Item was created (a file is recorded once its upload finalizes)
+            update: Item was renamed, re-described, moved, or had its content replaced
+            delete: Item was soft-deleted to the recycle bin
+            download: A presigned download URL was issued for the file
+            restore: Item was restored from the recycle bin
+            purge: Item was permanently purged
+          description: |-
+            Type of change. An item's history starts with `create`, gathers
+            `update` and `download` entries while it is live, and ends with
+            `delete` followed by either `restore` (back to live) or `purge`.
+          examples:
+            - update
+        source:
+          type: string
+          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, such as creating an integration's system folder
+          description: How the change was initiated.
           examples:
-            - manage
-        dependencyIds:
+            - api
+        time:
+          type: string
+          format: date-time
+          description: Timestamp when the change occurred.
+          examples:
+            - '2026-05-02T18:09:26.975Z'
+        byUser:
           type: object
-          description: |-
-            Map of resource types to arrays of IDs that this dependent
-            resource references on the target. Keys are singular or plural
-            resource type strings; values are arrays of ID strings.
-          additionalProperties:
-            type: array
-            items:
+          description: User who made the change.
+          properties:
+            _id:
               type: string
-          example:
-            script:
-              - 64ff4b21612a134bd2f45531
-      required:
-        - id
-        - name
-        - paths
-        - accessLevel
-        - dependencyIds
-    DependencyResponse:
-      type: object
-      description: |
-        Map of dependent-resource types to arrays of dependency entries.
-        Keys are plural resource type strings (e.g. `flows`, `imports`,
-        `connections`). An empty object `{}` means no dependents.
-      additionalProperties:
-        type: array
-        items:
-          $ref: '#/components/schemas/DependencyEntry'
-      example:
-        exports:
-          - id: 64ff4b21612a134bd2f45534
-            name: Bank FTP Export
-            paths:
-              - hooks.preSavePage._scriptId
-            accessLevel: manage
-            dependencyIds:
-              script:
-                - 64ff4b21612a134bd2f45531
-        flows:
-          - id: 64ff4b22612a134bd2f45538
-            name: CAMT-053 to Celigo CAM Format
-            paths:
-              - pageGenerators[*]._exportId
-            accessLevel: manage
-            dependencyIds:
-              export:
-                - 64ff4b21612a134bd2f45534
+              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:
+                - Jane Doe
+        fieldChanges:
+          type: array
+          description: Fields that were modified. Empty on `create` and `delete` entries.
+          items:
+            type: object
+            properties:
+              fieldPath:
+                type: string
+                description: Dot-notation path of the changed field.
+                examples:
+                  - name
+              oldValue:
+                description: Previous value (absent on create).
+              newValue:
+                description: New value (absent on delete).
+        deletedInfo:
+          type: object
+          description: Metadata about the deleted item. Present on `delete` events.
+          properties:
+            name:
+              type: string
+              description: Name of the item at the time of deletion.
+              examples:
+                - old-report.pdf
     Usage:
       type: object
       description: Account-wide storage usage and entitlement, aggregated across all environments.
@@ -3098,5 +3380,105 @@ components:
                 errors:
                   - code: unprocessable_entity
                     message: The request could not be processed due to a semantic error.
+  parameters:
+    Limit:
+      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
+    After:
+      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:
+          - W3siJGRhdGUiOiIyMDI2LTA5LTIyVDAzOjM0OjEzLjk5OVoifSwiNmFiMWY3MzZmOWY5N2M2ZThmMzUzYjVhIl0
+    From:
+      name: from
+      in: query
+      required: false
+      description: |-
+        Only return entries at or after this timestamp. Must be within the last
+        three years and not in the future.
+      schema:
+        type: string
+        format: date-time
+        examples:
+          - '2026-05-01T00:00:00.000Z'
+    To:
+      name: to
+      in: query
+      required: false
+      description: |-
+        Only return entries at or before this timestamp. Must be within the last
+        three years and not in the future.
+      schema:
+        type: string
+        format: date-time
+        examples:
+          - '2026-05-31T23:59:59.999Z'
+    Action:
+      name: action
+      in: query
+      required: false
+      description: Filter by the change type. Maps to the `event` field on each entry.
+      schema:
+        type: string
+        enum:
+          - create
+          - update
+          - delete
+          - download
+          - restore
+          - purge
+        examples:
+          - update
+        x-enumDescriptions:
+          create: An item was created
+          update: An item was renamed, re-described, moved, or had its content replaced
+          delete: An item was soft-deleted to the recycle bin
+          download: A presigned download URL was issued for a file
+          restore: An item was restored from the recycle bin
+          purge: An item was permanently purged from the recycle bin
+    Source:
+      name: source
+      in: query
+      required: false
+      description: Filter by how the change was initiated.
+      schema:
+        type: string
+        enum:
+          - api
+          - ui
+          - system
+        examples:
+          - api
+        x-enumDescriptions:
+          api: Change made via the REST API
+          ui: Change made through the Celigo UI
+          system: Change made automatically by the platform
+    ByUserId:
+      name: _byUserId
+      in: query
+      required: false
+      description: Filter to changes performed by a single user.
+      schema:
+        type: string
+        format: objectId
+        x-celigo-refModel: users
+        examples:
+          - 624cb0346309dc3a543733a2
 x-internal: false
 x-enable-proxy: true