@celigo/api-specs 0.2.1

package/dist/filestorage.yml

@@ -0,0 +1,3102 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: File Storage
+  description: Manage files and folders in Celigo Storage.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: File Storage
+    description: |-
+      Celigo Storage is managed file storage built into integrator.io for staging files between flows and giving integrations persistent files to work with. Organize content into files and folders, transfer bytes directly through short-lived presigned S3 URLs, and reference stored files from flows. Items are addressed by `_id` and placed by parent folder; renames and moves keep the `_id` stable, and deletes go to a 30-day recycle bin before they can be purged.
+
+      ## Storage item schema
+
+      {% openapi-schemas spec="filestorage" schemas="StorageItem" grouped="true" %}
+paths:
+  /v1/storage/files/initiateUpload:
+    post:
+      x-internal: false
+      summary: Initiate file upload
+      description: |-
+        Starts one or more file uploads. For each file, reserves quota, creates a
+        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
+        `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.
+      operationId: initiateStorageUpload
+      tags:
+        - File Storage
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/InitiateUploadRequest'
+            examples:
+              single:
+                summary: Single small file
+                value:
+                  _parentId: 683a1f2e9b0c4d001e8f7a23
+                  files:
+                    - name: logo.png
+                      mimeType: image/png
+                      size: 245760
+                      uploadType: single
+              multipart:
+                summary: Large file via multipart
+                value:
+                  files:
+                    - name: full-backup.zip
+                      mimeType: application/zip
+                      size: 8589934592
+                      uploadType: multipart
+                      numParts: 50
+              resumeMultipart:
+                summary: Request the next batch of part URLs
+                value:
+                  files:
+                    - _id: 683b2a0e1c3d5f001a9e8b03
+                      name: database-export.sql
+                      uploadType: multipart
+                      uploadId: abcD12efGHIjklMN3opQrst
+                      issuedPartsCount: 5
+                      numParts: 5
+      responses:
+        '200':
+          description: Per-file upload instructions, in request order.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InitiateUploadResponse'
+              examples:
+                mixed:
+                  summary: Single success, multipart success, and a rejection
+                  value:
+                    files:
+                      - _id: 683b2a0e1c3d5f001a9e8b01
+                        name: logo.png
+                        statusCode: 200
+                        body:
+                          uploadType: single
+                          uploadUrl: https://integrator-file-storage.s3.us-west-2.amazonaws.com/presigned-put-url
+                      - _id: 683b2a0e1c3d5f001a9e8b03
+                        name: database-export.sql
+                        statusCode: 200
+                        body:
+                          uploadType: multipart
+                          uploadId: abcD12efGHIjklMN3opQrst
+                          partUrls:
+                            - partNumber: 6
+                              url: https://integrator-file-storage.s3.us-west-2.amazonaws.com/part-6
+                            - partNumber: 7
+                              url: https://integrator-file-storage.s3.us-west-2.amazonaws.com/part-7
+                          completeUrl: https://integrator-file-storage.s3.us-west-2.amazonaws.com/complete
+                      - name: invalid-file
+                        statusCode: 400
+                        errors:
+                          - code: STORAGE_INVALID_MIME_TYPE
+                            message: Invalid MIME type
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/storage/files/refresh-urls:
+    post:
+      x-internal: false
+      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.
+      operationId: refreshStorageUploadUrls
+      tags:
+        - File Storage
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RefreshUrlsRequest'
+            examples:
+              mixed:
+                summary: Refresh a single PUT and a multipart batch
+                value:
+                  items:
+                    - _id: 683b2a0e1c3d5f001a9e8b01
+                      uploadType: single
+                    - _id: 683b2a0e1c3d5f001a9e8b03
+                      uploadType: multipart
+                      uploadId: abcD12efGHIjklMN3opQrst
+                      partNumbers:
+                        - 3
+                        - 4
+                        - 5
+      responses:
+        '200':
+          description: Per-item refreshed upload instructions.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RefreshUrlsResponse'
+              examples:
+                default:
+                  value:
+                    items:
+                      - _id: 683b2a0e1c3d5f001a9e8b03
+                        name: database-export.sql
+                        statusCode: 200
+                        body:
+                          uploadType: multipart
+                          uploadId: abcD12efGHIjklMN3opQrst
+                          partUrls:
+                            - partNumber: 3
+                              url: https://integrator-file-storage.s3.us-west-2.amazonaws.com/fresh-part-3
+                          completeUrl: https://integrator-file-storage.s3.us-west-2.amazonaws.com/fresh-complete
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/storage/files/{_id}/cancel:
+    post:
+      x-internal: false
+      summary: Cancel a multipart upload
+      description: |-
+        Aborts an in-progress multipart upload, discarding any uploaded parts and
+        releasing the reserved quota. Use this to abandon a multipart upload
+        started with `POST /v1/storage/files/initiateUpload`; single PUT uploads
+        do not need canceling. If the upload has in fact already completed in S3,
+        the item is activated instead and the request is rejected as not pending.
+      operationId: cancelStorageUpload
+      tags:
+        - File Storage
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: ID of the pending multipart item to cancel.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+            examples:
+              - 683b2a0e1c3d5f001a9e8b03
+      responses:
+        '204':
+          description: Multipart upload aborted and the pending item removed.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/storage/files/{_id}/download:
+    get:
+      x-internal: false
+      summary: Get a file download URL
+      description: |-
+        Returns a short-lived presigned S3 URL for downloading a file's content,
+        along with how many seconds it stays valid. Fetch the bytes directly from
+        that URL — the content does not pass through this API. Files only; folders
+        have no content to download.
+      operationId: getStorageFileDownloadUrl
+      tags:
+        - File Storage
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: ID of the file to download.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+            examples:
+              - 683b2a0e1c3d5f001a9e8b01
+      responses:
+        '200':
+          description: A presigned download URL and its lifetime.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - downloadUrl
+                  - expiresIn
+                properties:
+                  downloadUrl:
+                    type: string
+                    format: uri
+                    description: Presigned S3 URL to GET the file's bytes from.
+                    examples:
+                      - https://integrator-file-storage.s3.us-west-2.amazonaws.com/file-storage/...
+                  expiresIn:
+                    type: integer
+                    description: Seconds the URL stays valid from the time of this response.
+                    examples:
+                      - 3600
+              examples:
+                default:
+                  value:
+                    downloadUrl: https://integrator-file-storage.s3.us-west-2.amazonaws.com/file-storage/...
+                    expiresIn: 3600
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/storage/items:
+    get:
+      x-internal: false
+      summary: List or search items
+      description: |-
+        Browse or search Celigo Storage. In list mode (no `search`), returns the
+        direct children of a folder — omit `_parentId` for the account root — and
+        includes a `breadcrumb` of the path to that folder. In search mode (with
+        `search`), recursively matches item names across the whole account and
+        returns each hit's `location`. Results are paginated with the `Link`
+        response header.
+      operationId: listStorageItems
+      tags:
+        - File Storage
+      parameters:
+        - name: _parentId
+          in: query
+          required: false
+          description: |-
+            Folder whose direct children to list. Omit for the account root.
+            Ignored in search mode.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+            examples:
+              - 683a1f2e9b0c4d001e8f7a23
+        - name: search
+          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.
+          schema:
+            type: string
+            minLength: 2
+            examples:
+              - report
+        - name: type
+          in: query
+          required: false
+          description: Restrict results to one item type.
+          schema:
+            type: string
+            enum:
+              - file
+              - folder
+            x-enumDescriptions:
+              file: Return only files.
+              folder: Return only folders.
+            examples:
+              - file
+        - name: mimeType
+          in: query
+          required: false
+          description: Restrict results to files of a single media type.
+          schema:
+            type: string
+            examples:
+              - image/png
+        - name: sort_by
+          in: query
+          required: false
+          description: Field to sort by.
+          schema:
+            type: string
+            enum:
+              - name
+              - lastModified
+            default: name
+            x-enumDescriptions:
+              name: Sort alphabetically by name.
+              lastModified: Sort by the last-modified timestamp.
+            examples:
+              - name
+        - name: sort_order
+          in: query
+          required: false
+          description: Sort direction.
+          schema:
+            type: string
+            enum:
+              - asc
+              - desc
+            default: asc
+            x-enumDescriptions:
+              asc: Ascending — A→Z for name, oldest first for lastModified.
+              desc: Descending — Z→A for name, newest first for lastModified.
+            examples:
+              - asc
+        - name: lastModified_gte
+          in: query
+          required: false
+          description: Return only items modified at or after this time.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-03-01T00:00:00.000Z'
+        - name: lastModified_lte
+          in: query
+          required: false
+          description: Return only items modified at or before this time.
+          schema:
+            type: string
+            format: date-time
+            examples:
+              - '2026-03-31T23:59:59.999Z'
+        - name: pageSize
+          in: query
+          required: false
+          description: Maximum number of items to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+            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:
+              - eyJsYXN0SWQiOiI2ODNiMmEwZTFjM2Q1ZjAwMWE5ZThiMDEifQ
+        - 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:
+              - eyJmaXJzdElkIjoiNjg0YzNiMWYyZDRlNmcwMDJiMGg5YzM0In0
+      responses:
+        '200':
+          description: |-
+            Matching items. Includes `breadcrumb` in list mode and per-item
+            `location` in search mode.
+          headers:
+            Link:
+              description: |-
+                RFC 5988 pagination links. Includes `<...>; rel="next"` (and
+                `rel="prev"` when paging backward) with cursor params; the
+                `rel="next"` entry is absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - items
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/StorageItem'
+                  breadcrumb:
+                    type: array
+                    description: |-
+                      Path from the root to the listed folder, nearest the root
+                      first. Present in list mode when `_parentId` is set.
+                    items:
+                      type: object
+                      properties:
+                        _id:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: storageitems
+                          description: Folder ID.
+                          examples:
+                            - 683a1f2e9b0c4d001e8f7a23
+                        name:
+                          type: string
+                          description: Folder name.
+                          examples:
+                            - My Files
+              examples:
+                listMode:
+                  summary: List a folder's children
+                  value:
+                    items:
+                      - _id: 684c3b1f2d4e6g002b0h9c34
+                        type: folder
+                        name: Reports
+                        status: active
+                        isSystem: false
+                        createdAt: '2026-03-28T10:00:00.000Z'
+                        lastModified: '2026-03-28T14:30:00.000Z'
+                      - _id: 683b2a0e1c3d5f001a9e8b01
+                        type: file
+                        name: logo.png
+                        size: 245760
+                        mimeType: image/png
+                        status: active
+                        isSystem: false
+                        createdAt: '2026-03-28T09:00:00.000Z'
+                        lastModified: '2026-03-28T09:00:00.000Z'
+                    breadcrumb:
+                      - _id: 683a1f2e9b0c4d001e8f7a23
+                        name: My Files
+                searchMode:
+                  summary: Search by name
+                  value:
+                    items:
+                      - _id: 683b2a0e1c3d5f001a9e8b01
+                        type: file
+                        name: logo.png
+                        size: 245760
+                        mimeType: image/png
+                        status: active
+                        isSystem: false
+                        location:
+                          _id: 683a1f2e9b0c4d001e8f7a23
+                          name: My Files
+                        createdAt: '2026-03-28T09:00:00.000Z'
+                        lastModified: '2026-03-28T09:00:00.000Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    post:
+      x-internal: false
+      summary: Create a folder
+      description: |-
+        Creates an empty folder. Folders are organizational only — they hold no
+        content and do not count against storage quota. To create files, use
+        `POST /v1/storage/files/initiateUpload`.
+      operationId: createStorageFolder
+      tags:
+        - File Storage
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateFolderRequest'
+            examples:
+              rootFolder:
+                summary: Folder at the account root
+                value:
+                  name: Reports
+              nestedFolder:
+                summary: Folder inside another folder
+                value:
+                  name: Reports
+                  _parentId: 683a1f2e9b0c4d001e8f7a23
+                  description: Quarterly financial reports
+      responses:
+        '201':
+          description: Created folder.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StorageItem'
+              examples:
+                default:
+                  value:
+                    _id: 684c3b1f2d4e6g002b0h9c34
+                    type: folder
+                    name: Reports
+                    description: Quarterly financial reports
+                    status: active
+                    isSystem: false
+                    createdAt: '2026-03-30T10:30:00.000Z'
+                    lastModified: '2026-03-30T10:30:00.000Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/storage/items/batch:
+    post:
+      x-internal: false
+      summary: Look up items in batch
+      description: |-
+        Returns metadata for up to 100 items in one call. Send the item ids and
+        optionally a `fields` projection; by default each result carries only
+        `_id`. Requesting `path` adds a breadcrumb path built from the item's
+        ancestor folder names.
+
+        With `failFast: true` (the default), the first unknown id fails the whole
+        request with `422 STORAGE_BATCH_ITEM_NOT_FOUND`. With `failFast: false`,
+        unknown ids come back inline as
+        `{_id, notFound: true, reason: "STORAGE_BATCH_ITEM_NOT_FOUND"}` entries
+        alongside the found items.
+      operationId: batchGetStorageItems
+      tags:
+        - File Storage
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - ids
+              properties:
+                ids:
+                  type: array
+                  minItems: 1
+                  maxItems: 100
+                  description: |-
+                    Item ids to look up. Each must be a 24-character ObjectId;
+                    a malformed id fails the request with
+                    `400 STORAGE_BATCH_INVALID_REQUEST` before any lookup runs.
+                  items:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: storageitems
+                  examples:
+                    - - 683b2a0e1c3d5f001a9e8b01
+                      - 684c3b1f2d4e6a002b0f9c34
+                fields:
+                  type: array
+                  minItems: 1
+                  description: |-
+                    Which fields to return per item (`_id` is always included).
+                    Omitted means `_id` only. An unknown field name fails with
+                    `400 STORAGE_BATCH_INVALID_REQUEST` naming the allowed set.
+                  items:
+                    type: string
+                    enum:
+                      - name
+                      - description
+                      - size
+                      - mimeType
+                      - type
+                      - status
+                      - _parentId
+                      - __ancestorIds
+                      - path
+                    x-enumDescriptions:
+                      name: Item name.
+                      description: Item description.
+                      size: File size in bytes.
+                      mimeType: File MIME type.
+                      type: Item type (`file` or `folder`).
+                      status: Item lifecycle status.
+                      _parentId: Parent folder id.
+                      __ancestorIds: Ancestor folder id chain from the root.
+                      path: Breadcrumb path built from ancestor folder names, e.g. `/invoices/2026/inv-001.pdf`.
+                  examples:
+                    - - name
+                      - size
+                      - path
+                failFast:
+                  type: boolean
+                  default: true
+                  description: |-
+                    When true (the default), an unknown id fails the whole request
+                    with 422. When false, unknown ids are reported inline per item
+                    and the request still returns 200.
+            examples:
+              projection:
+                summary: Look up names and paths, tolerating unknown ids
+                value:
+                  ids:
+                    - 683b2a0e1c3d5f001a9e8b01
+                    - 684c3b1f2d4e6a002b0f9c34
+                  fields:
+                    - name
+                    - size
+                    - path
+                  failFast: false
+      responses:
+        '200':
+          description: Per-id results, in the same order as the requested `ids`.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  items:
+                    type: array
+                    description: One entry per requested id, in request order.
+                    items:
+                      type: object
+                      required:
+                        - _id
+                      properties:
+                        _id:
+                          type: string
+                          format: objectId
+                          x-celigo-refModel: storageitems
+                          description: Item id this entry corresponds to.
+                        name:
+                          type: string
+                          description: Present when requested via `fields`.
+                        size:
+                          type: integer
+                          description: File size in bytes. Present when requested via `fields`.
+                        path:
+                          type: string
+                          description: |-
+                            Breadcrumb path from the root, built from ancestor
+                            folder names. Present when requested via `fields`.
+                          examples:
+                            - /invoices/2026/inv-001.pdf
+                        notFound:
+                          type: boolean
+                          description: |-
+                            Present (true) only on unknown ids when
+                            `failFast: false`.
+                        reason:
+                          type: string
+                          description: |-
+                            Error code for an unknown id when `failFast: false`
+                            (`STORAGE_BATCH_ITEM_NOT_FOUND`).
+              examples:
+                mixed:
+                  summary: One found, one unknown (failFast false)
+                  value:
+                    items:
+                      - _id: 683b2a0e1c3d5f001a9e8b01
+                        name: inv-001.pdf
+                        size: 18244
+                        path: /invoices/2026/inv-001.pdf
+                      - _id: 684c3b1f2d4e6a002b0f9c34
+                        notFound: true
+                        reason: STORAGE_BATCH_ITEM_NOT_FOUND
+        '400':
+          description: |-
+            Malformed request — `ids` missing/empty/over 100 entries, a
+            non-ObjectId id, an unknown `fields` entry, or a non-boolean
+            `failFast`. Error code: `STORAGE_BATCH_INVALID_REQUEST`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: |-
+            An id was not found while `failFast` was true (the default). Each
+            error entry carries the offending `_id`.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  errors:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        code:
+                          type: string
+                          description: Error code (`STORAGE_BATCH_ITEM_NOT_FOUND`).
+                        message:
+                          type: string
+                          description: Human-readable error message naming the id.
+                        _id:
+                          type: string
+                          format: objectId
+                          description: The id that was not found.
+              examples:
+                not_found:
+                  value:
+                    errors:
+                      - code: STORAGE_BATCH_ITEM_NOT_FOUND
+                        message: 'File not found: 684c3b1f2d4e6a002b0f9c34'
+                        _id: 684c3b1f2d4e6a002b0f9c34
+  /v1/storage/items/move:
+    post:
+      x-internal: false
+      summary: Move items in bulk
+      description: |-
+        Moves up to 100 files or folders into one destination folder (or the
+        account root) in a single call. Metadata only — content stays in place,
+        ids are unchanged, and quota is unaffected. Folders re-parent immediately
+        and re-anchor their descendants asynchronously.
+
+        The destination is validated once up front — a bad destination rejects the
+        whole batch. Each source id is then processed best-effort: the response is
+        `200` when every item moved, or `207` when results are mixed, with a
+        per-id `status` of `success` or `error`. An optional `name` renames the
+        item as it lands (single-id requests only) so a destination name collision
+        can be resolved without a second call.
+      operationId: bulkMoveStorageItems
+      tags:
+        - File Storage
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - _parentFolderId
+                - _storageItemIds
+              properties:
+                _parentFolderId:
+                  type:
+                    - string
+                    - 'null'
+                  format: objectId
+                  x-celigo-refModel: storageitems
+                  description: |-
+                    Destination folder. Send null to move the items to the account
+                    root. The key must be present — omitting it fails with
+                    `400 STORAGE_BULK_MOVE_PARENT_REQUIRED`. Must not appear in
+                    `_storageItemIds` (`422 STORAGE_BULK_MOVE_DESTINATION_IN_SOURCES`).
+                  examples:
+                    - 684c3b1f2d4e6a002b0f9c34
+                _storageItemIds:
+                  type: array
+                  minItems: 1
+                  maxItems: 100
+                  description: |-
+                    Ids of the items to move. Over 100 entries fails with
+                    `422 STORAGE_BULK_MOVE_TOO_MANY_ITEMS`.
+                  items:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: storageitems
+                  examples:
+                    - - 683b2a0e1c3d5f001a9e8b01
+                name:
+                  type: string
+                  description: |-
+                    New name applied to the moved item in the same write as the
+                    re-parent. Only allowed when `_storageItemIds` has exactly one
+                    entry — with more, the request fails with
+                    `400 STORAGE_BULK_MOVE_NAME_DISALLOWED`.
+            examples:
+              bulk:
+                summary: Move two items into a folder
+                value:
+                  _parentFolderId: 684c3b1f2d4e6a002b0f9c34
+                  _storageItemIds:
+                    - 683b2a0e1c3d5f001a9e8b01
+                    - 683b2a0e1c3d5f001a9e8b02
+              rename_on_move:
+                summary: Move one item to the root and rename it
+                value:
+                  _parentFolderId: null
+                  _storageItemIds:
+                    - 683b2a0e1c3d5f001a9e8b01
+                  name: inv-001-final.pdf
+      responses:
+        '200':
+          description: Every item moved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BulkMoveResults'
+              examples:
+                all_success:
+                  value:
+                    results:
+                      - _id: 683b2a0e1c3d5f001a9e8b01
+                        status: success
+                        _parentId: 684c3b1f2d4e6a002b0f9c34
+                        __ancestorIds:
+                          - 684c3b1f2d4e6a002b0f9c34
+                        type: file
+        '207':
+          description: |-
+            Mixed results — at least one item failed to move. Inspect each
+            entry's `status`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BulkMoveResults'
+              examples:
+                mixed:
+                  value:
+                    results:
+                      - _id: 683b2a0e1c3d5f001a9e8b01
+                        status: success
+                        _parentId: 684c3b1f2d4e6a002b0f9c34
+                        __ancestorIds:
+                          - 684c3b1f2d4e6a002b0f9c34
+                        type: file
+                      - _id: 683b2a0e1c3d5f001a9e8b02
+                        status: error
+                        errorCode: STORAGE_MOVE_SAME_PARENT_DISALLOWED
+                        message: The item is already in the destination folder
+        '400':
+          description: |-
+            Malformed request — `_parentFolderId` key missing
+            (`STORAGE_BULK_MOVE_PARENT_REQUIRED`), `_storageItemIds`
+            missing or empty (`STORAGE_BULK_MOVE_IDS_REQUIRED`), or `name` sent
+            with more than one id (`STORAGE_BULK_MOVE_NAME_DISALLOWED`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: |-
+            Batch-level rejection — too many ids
+            (`STORAGE_BULK_MOVE_TOO_MANY_ITEMS`), the destination appears among
+            the source ids (`STORAGE_BULK_MOVE_DESTINATION_IN_SOURCES`), or the
+            destination is not a folder.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/storage/items/recycleBinTTL:
+    get:
+      x-internal: false
+      summary: List recycle-bin items
+      description: |-
+        Lists the items currently in the recycle bin, newest deletion first. Only
+        items deleted directly are listed — descendants removed as part of a
+        folder deletion are hidden, since they are restored or purged with their
+        parent. Each item carries `deletedAt` and `deletedBy`. Restore an item
+        with `POST /v1/storage/items/{_id}/restore` or remove it for good with
+        `DELETE /v1/storage/items/{_id}/purge`.
+      operationId: listStorageRecycleBin
+      tags:
+        - File Storage
+      parameters:
+        - name: pageSize
+          in: query
+          required: false
+          description: Maximum number of items to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 1000
+            examples:
+              - 100
+        - name: after
+          in: query
+          required: false
+          description: |-
+            Opaque forward-paging cursor. Take it from the previous response's
+            `Link` header (`rel="next"`); omit for the first page. Cannot be
+            combined with `before`.
+          schema:
+            type: string
+            examples:
+              - WyIyMDI2LTA4LTA5VDA0OjQ2OjUwLjI0NloiLCI2YTc3ZmQ0YTAxYjgxODdjMmYzNGEzOGEiLCJkZWxldGVkQXQiLCJkZXNjIl0
+        - name: before
+          in: query
+          required: false
+          description: |-
+            Opaque backward-paging cursor from a previous response's `Link`
+            header. Cannot be combined with `after`.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: |-
+            Recycle-bin items. Pagination is cursor-based via the `Link`
+            header — the body carries only `items`.
+          headers:
+            Link:
+              description: |-
+                RFC-5988 pagination links. When more pages remain, includes a
+                `<...?after=...>; rel="next"` entry; absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - items
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/StorageItem'
+              examples:
+                default:
+                  value:
+                    items:
+                      - _id: 683b2a0e1c3d5f001a9e8b01
+                        type: file
+                        name: old-report.pdf
+                        size: 245760
+                        mimeType: application/pdf
+                        status: active
+                        isSystem: false
+                        deletedBy: 60a1b2c3d4e5f6001a2b3c4d
+                        deletedAt: '2026-04-27T10:00:00.000Z'
+                        createdAt: '2026-03-01T09:00:00.000Z'
+                        lastModified: '2026-03-28T10:00:00.000Z'
+                      - _id: 684c3b1f2d4e6g002b0h9c34
+                        type: folder
+                        name: Archived Reports
+                        status: active
+                        isSystem: false
+                        deletedBy: 60a1b2c3d4e5f6001a2b3c4d
+                        deletedAt: '2026-04-25T14:30:00.000Z'
+                        createdAt: '2026-02-15T08:00:00.000Z'
+                        lastModified: '2026-03-26T14:30:00.000Z'
+        '400':
+          description: |-
+            The `after`/`before` cursor is malformed, was not issued by this
+            listing, or both were sent together. Error code:
+            `STORAGE_INVALID_CURSOR`. Restart from the first page (omit the
+            cursor).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_cursor:
+                  value:
+                    errors:
+                      - code: STORAGE_INVALID_CURSOR
+                        message: Invalid or corrupted cursor
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+  /v1/storage/items/{_id}:
+    put:
+      x-internal: false
+      summary: Rename or describe an item
+      description: |-
+        Updates an item's `name` and/or `description`. Renaming keeps the item's
+        `_id` stable, so references from flows, exports, imports, and tokens
+        survive. 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
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Item ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+            examples:
+              - 683b2a0e1c3d5f001a9e8b01
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateRequest'
+            examples:
+              rename:
+                summary: Rename and update description
+                value:
+                  name: quarterly-report-final.pdf
+                  description: Updated Q1 2026 financial report
+      responses:
+        '200':
+          description: Updated item.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StorageItem'
+              examples:
+                default:
+                  value:
+                    _id: 683b2a0e1c3d5f001a9e8b01
+                    type: file
+                    name: quarterly-report-final.pdf
+                    description: Updated Q1 2026 financial report
+                    size: 245760
+                    mimeType: application/pdf
+                    status: active
+                    isSystem: false
+                    createdAt: '2026-03-28T10:00:00.000Z'
+                    lastModified: '2026-03-28T14:30:00.000Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      summary: Delete an item
+      description: |-
+        Soft-deletes a file or folder to the recycle bin, where it is retained
+        for 30 days and can be restored with
+        `POST /v1/storage/items/{_id}/restore`. Deleting a folder also removes
+        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`.
+      operationId: deleteStorageItem
+      tags:
+        - File Storage
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Item ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+            examples:
+              - 683b2a0e1c3d5f001a9e8b01
+      responses:
+        '204':
+          description: |-
+            Item soft-deleted. For a folder, the root is removed and its
+            descendants are removed asynchronously.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/storage/items/{_id}/replace:
+    patch:
+      x-internal: false
+      summary: Replace file content
+      description: |-
+        Overwrites an existing file's content in place. Returns presigned upload
+        URLs in the same shape as one initiate-upload file entry; transfer the new
+        bytes to them just as for a new upload. The item's `_id`, name, and folder
+        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
+        endpoint does not accept a name.
+      operationId: replaceStorageFileContent
+      tags:
+        - File Storage
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: ID of the file to replace.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+            examples:
+              - 683b2a0e1c3d5f001a9e8b01
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ReplaceRequest'
+            examples:
+              single:
+                summary: Replace with a single PUT
+                value:
+                  mimeType: application/pdf
+                  size: 5242880
+                  uploadType: single
+              multipart:
+                summary: Replace with a multipart upload
+                value:
+                  mimeType: application/pdf
+                  size: 5242880
+                  uploadType: multipart
+                  numParts: 5
+              resumeMultipart:
+                summary: Request the next batch of part URLs
+                value:
+                  uploadType: multipart
+                  numParts: 5
+                  uploadId: abcD12efGHIjklMN3opQrst
+                  issuedPartsCount: 5
+      responses:
+        '200':
+          description: Upload instructions for the replacement content.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UploadResult'
+              examples:
+                single:
+                  summary: Single PUT
+                  value:
+                    _id: 683b2a0e1c3d5f001a9e8b01
+                    name: quarterly-report.pdf
+                    statusCode: 200
+                    body:
+                      uploadType: single
+                      uploadUrl: https://integrator-file-storage.s3.us-west-2.amazonaws.com/presigned-put-url
+                multipart:
+                  summary: Multipart
+                  value:
+                    _id: 683b2a0e1c3d5f001a9e8b01
+                    name: quarterly-report.pdf
+                    statusCode: 200
+                    body:
+                      uploadType: multipart
+                      uploadId: abcD12efGHIjklMN3opQrst
+                      partUrls:
+                        - partNumber: 1
+                          url: https://integrator-file-storage.s3.us-west-2.amazonaws.com/part-1
+                        - partNumber: 2
+                          url: https://integrator-file-storage.s3.us-west-2.amazonaws.com/part-2
+                      completeUrl: https://integrator-file-storage.s3.us-west-2.amazonaws.com/complete
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '409':
+          description: |-
+            A concurrent replace is already in progress for this file
+            (`STORAGE_ITEM_REPLACE_CONFLICT`). Retry once the in-flight
+            replacement finalizes or is abandoned.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                default:
+                  value:
+                    errors:
+                      - code: STORAGE_ITEM_REPLACE_CONFLICT
+                        message: A replacement upload is already in progress for this file.
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/storage/items/{_id}/merge:
+    post:
+      x-internal: false
+      summary: Merge a folder into another
+      description: |-
+        Merges the contents of a source folder into an existing destination
+        folder, then removes the source. Runs asynchronously: the request is
+        validated and queued, and the endpoint immediately returns `202` with a
+        job receipt — contents move in the background and the source folder
+        disappears once the merge completes. 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.
+      operationId: mergeStorageFolder
+      tags:
+        - File Storage
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: ID of the source folder to merge and remove.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+            examples:
+              - 6a6e1d9e6ac4879f0ac8006f
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MergeRequest'
+            examples:
+              default:
+                summary: Merge into another folder
+                value:
+                  _destinationId: 6a6e1d9e7042f856e8d731ab
+      responses:
+        '202':
+          description: |-
+            Merge accepted and queued. The source folder remains visible until
+            the background job completes, then is removed.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - jobId
+                  - jobType
+                  - status
+                  - sourceFolderId
+                  - _destinationId
+                properties:
+                  jobId:
+                    type: string
+                    description: Identifier of the queued merge job.
+                    examples:
+                      - f6b61847-40a8-4c74-91b6-0e641dccee13
+                  jobType:
+                    type: string
+                    enum:
+                      - folderMerge
+                    x-enumDescriptions:
+                      folderMerge: Asynchronous folder-merge job.
+                    description: Kind of background job that was queued.
+                  status:
+                    type: string
+                    enum:
+                      - accepted
+                    x-enumDescriptions:
+                      accepted: The merge was validated and queued for processing.
+                    description: Acknowledgement state of the request.
+                  sourceFolderId:
+                    type: string
+                    format: objectId
+                    description: The source folder being merged and removed.
+                    examples:
+                      - 6a6e1d9e6ac4879f0ac8006f
+                  _destinationId:
+                    type: string
+                    format: objectId
+                    description: The folder receiving the source folder's contents.
+                    examples:
+                      - 6a6e1d9e7042f856e8d731ab
+              examples:
+                accepted:
+                  value:
+                    jobId: f6b61847-40a8-4c74-91b6-0e641dccee13
+                    jobType: folderMerge
+                    status: accepted
+                    sourceFolderId: 6a6e1d9e6ac4879f0ac8006f
+                    _destinationId: 6a6e1d9e7042f856e8d731ab
+        '400':
+          description: '`_destinationId` is missing from the request body.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missing_destination:
+                  value:
+                    errors:
+                      - code: STORAGE_MERGE_DESTINATION_REQUIRED
+                        message: _destinationId is required in the request body
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            Caller lacks delete access on the source or write access on the
+            destination, the source is a protected system folder, or the account
+            is not entitled to Celigo Storage.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: The source or destination folder does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '422':
+          description: |-
+            The merge is structurally invalid — the source or destination is not
+            a folder, the source and destination are the same folder, the
+            destination sits inside the source (circular merge), or the merged
+            tree would exceed the maximum folder depth.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/storage/items/{_id}/move:
+    patch:
+      x-internal: false
+      summary: Move an item
+      description: |-
+        Moves a file or folder to a different folder. Metadata only — the content
+        stays in place, the item's `_id` is unchanged so references survive, and
+        quota is unaffected. Moving a folder re-parents the folder immediately and
+        re-anchors its descendants asynchronously, so the response reflects only
+        the moved item itself. A folder cannot be moved into itself or one of its
+        own descendants.
+      operationId: moveStorageItem
+      tags:
+        - File Storage
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: ID of the item to move.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+            examples:
+              - 683b2a0e1c3d5f001a9e8b01
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MoveRequest'
+            examples:
+              toFolder:
+                summary: Move into a folder
+                value:
+                  _parentId: 684c3b1f2d4e6g002b0h9c34
+              toRoot:
+                summary: Move to the account root
+                value:
+                  _parentId: null
+      responses:
+        '200':
+          description: |-
+            The moved item's changed fields. Only the item's own re-parenting is
+            reflected; for a folder, descendants re-anchor asynchronously.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - _id
+                properties:
+                  _id:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: storageitems
+                    description: ID of the moved item.
+                    examples:
+                      - 683b2a0e1c3d5f001a9e8b01
+                  _parentId:
+                    type:
+                      - string
+                      - 'null'
+                    format: objectId
+                    x-celigo-refModel: storageitems
+                    description: New parent folder, or null if moved to the root.
+                    examples:
+                      - 684c3b1f2d4e6g002b0h9c34
+                  __ancestorIds:
+                    type: array
+                    description: New ancestor chain from the root to the parent.
+                    items:
+                      type: string
+                      format: objectId
+                      x-celigo-refModel: storageitems
+                    examples:
+                      - - 684c3b1f2d4e6g002b0h9c34
+              examples:
+                default:
+                  value:
+                    _id: 683b2a0e1c3d5f001a9e8b01
+                    _parentId: 684c3b1f2d4e6g002b0h9c34
+                    __ancestorIds:
+                      - 684c3b1f2d4e6g002b0h9c34
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/storage/items/{_id}/copy:
+    post:
+      x-internal: false
+      summary: Copy a file
+      description: |-
+        Creates an independent copy of a file in a destination folder, with a new
+        `_id` and its own copy of the content. Consumes quota equal to the source
+        file's size. Files only — folder copy is not supported. Names are not
+        deduplicated, so copying into the source's own folder without a new name
+        produces a second file with the same name.
+      operationId: copyStorageFile
+      tags:
+        - File Storage
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: ID of the file to copy.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+            examples:
+              - 683b2a0e1c3d5f001a9e8b01
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CopyRequest'
+            examples:
+              rename:
+                summary: Copy into a folder with a new name
+                value:
+                  _destinationId: 684c3b1f2d4e6g002b0h9c34
+                  name: quarterly-report-copy.pdf
+              toRoot:
+                summary: Copy to the account root, keeping the name
+                value:
+                  _destinationId: null
+      responses:
+        '201':
+          description: The newly created copy.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StorageItem'
+              examples:
+                default:
+                  value:
+                    _id: 685d4c2g3e5f7h003c1i0d45
+                    type: file
+                    name: quarterly-report-copy.pdf
+                    _parentId: 684c3b1f2d4e6g002b0h9c34
+                    size: 5242880
+                    mimeType: application/pdf
+                    description: Q1 2026 financial report
+                    status: active
+                    isSystem: false
+                    createdAt: '2026-04-20T10:00:00.000Z'
+                    lastModified: '2026-04-20T10:00:00.000Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/storage/items/{_id}/restore:
+    post:
+      x-internal: false
+      summary: Restore an item
+      description: |-
+        Restores a soft-deleted item from the recycle bin back to its original
+        location. Restoring a folder also restores the descendants that were
+        removed with it; the folder comes back immediately and its descendants
+        follow asynchronously. Only items deleted directly can be restored — a
+        descendant removed by its parent's deletion comes back only when that
+        parent folder is restored.
+      operationId: restoreStorageItem
+      tags:
+        - File Storage
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: ID of the recycle-bin item to restore.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+            examples:
+              - 683b2a0e1c3d5f001a9e8b01
+      responses:
+        '204':
+          description: |-
+            Item restored. For a folder, the root is restored and its descendants
+            follow asynchronously.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/storage/items/{_id}/purge:
+    delete:
+      x-internal: false
+      summary: Purge an item
+      description: |-
+        Permanently deletes a soft-deleted item from the recycle bin and frees its
+        storage. This cannot be undone. Purging a folder also purges its
+        descendants; the folder and its subtree are removed asynchronously. Only
+        items deleted directly can be purged — a descendant removed by its
+        parent's deletion is purged together with that parent. The item must
+        already be in the recycle bin.
+      operationId: purgeStorageItem
+      tags:
+        - File Storage
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: ID of the recycle-bin item to purge.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+            examples:
+              - 683b2a0e1c3d5f001a9e8b01
+      responses:
+        '204':
+          description: |-
+            Item permanently deleted. For a folder, the subtree is purged
+            asynchronously.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/storage/items/{_id}/dependencies:
+    get:
+      x-internal: false
+      operationId: listStorageItemDependencies
+      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.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Item ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+            examples:
+              - 683b2a0e1c3d5f001a9e8b01
+      responses:
+        '200':
+          description: |-
+            Dependency map. Keys are resource-type strings; values are arrays of
+            dependency entries. Returns `{}` when nothing references the item.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DependencyResponse'
+              examples:
+                withDependents:
+                  summary: Item referenced by a flow
+                  value:
+                    flows:
+                      - id: 673e486ac12b3453ea0ba99a
+                        name: Nightly export
+                        paths:
+                          - pageGenerators[*]._exportId
+                        accessLevel: manage
+                        dependencyIds:
+                          export:
+                            - 673e486adc497ab5e649f1ca
+                empty:
+                  summary: No dependents
+                  value: {}
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/storageitems/{_id}/audit:
+    get:
+      x-internal: false
+      summary: Get audit log for an item
+      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.
+      tags:
+        - File Storage
+      operationId: getStorageItemAudit
+      parameters:
+        - name: _id
+          in: path
+          description: Item 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
+      responses:
+        '200':
+          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:
+                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
+              examples:
+                default:
+                  value:
+                    - _id: 69f63dd77009ea11abf0bce3
+                      resourceType: storageitem
+                      _resourceId: 683b2a0e1c3d5f001a9e8b01
+                      source: api
+                      event: update
+                      time: '2026-05-02T18:09:26.975Z'
+                      byUser:
+                        _id: 624cb0346309dc3a543733a2
+                        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.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/storage/usage:
+    get:
+      x-internal: false
+      summary: Get storage usage
+      description: |-
+        Returns account-wide storage usage and entitlement, aggregated across all
+        environments: bytes in use (active and recycle bin), the licensed quota,
+        the hard limit at which uploads are blocked, and whether the account is in
+        overage.
+      operationId: getStorageUsage
+      tags:
+        - File Storage
+      parameters:
+        - name: includeSystem
+          in: query
+          required: false
+          description: When true, also returns `systemUsage` — the bytes consumed by system items.
+          schema:
+            type: boolean
+            default: false
+            examples:
+              - true
+      responses:
+        '200':
+          description: Account-wide usage and entitlement.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Usage'
+              examples:
+                default:
+                  value:
+                    activeUsage: 536870912
+                    recycleBinUsage: 104857600
+                    totalUsage: 641728512
+                    systemUsage: 52428800
+                    maxAllowedUsage: 1073741824
+                    isOverage: false
+                    hardLimit: 1288490188
+                    overage: 0
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/storage/usage/environments:
+    get:
+      x-internal: false
+      summary: Get storage usage by environment
+      description: |-
+        Returns the same account-wide totals as `GET /v1/storage/usage`, broken
+        down per environment. Use it to see which environment is consuming the
+        account's shared quota.
+      operationId: getStorageUsageByEnvironment
+      tags:
+        - File Storage
+      parameters:
+        - name: includeSystem
+          in: query
+          required: false
+          description: When true, also returns `systemUsage` in the account-wide totals.
+          schema:
+            type: boolean
+            default: false
+            examples:
+              - true
+      responses:
+        '200':
+          description: Per-environment breakdown with account-wide totals.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UsageEnvironments'
+              examples:
+                default:
+                  value:
+                    environments:
+                      - _envUserId: 60a1b2c3d4e5f6001a2b3c4d
+                        name: Production
+                        activeUsage: 429496729
+                        recycleBinUsage: 52428800
+                        totalUsage: 481925529
+                      - _envUserId: 60a1b2c3d4e5f6001a2b3c4e
+                        name: Sandbox
+                        activeUsage: 107374182
+                        recycleBinUsage: 52428800
+                        totalUsage: 159802982
+                    activeUsage: 536870912
+                    recycleBinUsage: 104857600
+                    totalUsage: 641728512
+                    maxAllowedUsage: 1073741824
+                    isOverage: false
+                    hardLimit: 1288490188
+                    overage: 0
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    UploadRequestFile:
+      type: object
+      description: One file to upload within an initiate-upload request.
+      required:
+        - name
+        - uploadType
+      properties:
+        _id:
+          type: string
+          format: objectId
+          x-celigo-refModel: storageitems
+          description: |-
+            Existing pending item to continue. Set it only to request the next
+            batch of part URLs for an in-progress multipart upload, alongside
+            `uploadId` and `issuedPartsCount`. Omit for a new upload.
+          examples:
+            - 683b2a0e1c3d5f001a9e8b03
+        name:
+          type: string
+          maxLength: 256
+          description: File name, including extension. Duplicate names in a folder are allowed.
+          examples:
+            - logo.png
+        mimeType:
+          type: string
+          maxLength: 256
+          description: |-
+            Media type to record for the file and serve as its download
+            Content-Type. Optional; sniffed by callers from the file extension
+            when omitted.
+          examples:
+            - image/png
+        size:
+          type: integer
+          format: int64
+          minimum: 0
+          description: |-
+            Declared size in bytes. Used to reserve quota up front. When omitted,
+            the backend reserves a worst-case estimate (1 GB for single,
+            `numParts` × 5 GB for multipart) and reconciles to the real size when
+            the upload finalizes.
+          examples:
+            - 245760
+        uploadType:
+          type: string
+          enum:
+            - single
+            - multipart
+          x-enumDescriptions:
+            single: One presigned PUT for the whole file. Use for files up to 5 GB.
+            multipart: Chunked upload with per-part URLs. Required beyond 5 GB.
+          description: |-
+            How the file will be transferred. Use single for files up to 5 GB;
+            use multipart for larger files, which returns per-part URLs plus a
+            complete URL.
+        numParts:
+          type: integer
+          minimum: 1
+          description: |-
+            Total number of parts the file will be split into. Required when
+            uploadType is multipart; the response returns presigned URLs for as
+            many parts as the part budget allows.
+          examples:
+            - 50
+        uploadId:
+          type: string
+          description: |-
+            S3 multipart upload ID from a prior initiate response. Provide with
+            `issuedPartsCount` (and `_id`) to resume and request the next batch
+            of part URLs.
+          examples:
+            - abcD12efGHIjklMN3opQrst
+        issuedPartsCount:
+          type: integer
+          minimum: 0
+          description: |-
+            Number of part URLs already issued for this upload. Provide together
+            with `uploadId` to resume; the response continues numbering after
+            this value.
+          examples:
+            - 5
+    InitiateUploadRequest:
+      type: object
+      description: Reserves quota and requests presigned upload URLs for one or more files.
+      required:
+        - files
+      properties:
+        _parentId:
+          type:
+            - string
+            - 'null'
+          format: objectId
+          x-celigo-refModel: storageitems
+          description: |-
+            Folder to create the files in. Omit or pass null to upload to the
+            account root. Must reference an existing active folder.
+          examples:
+            - 683a1f2e9b0c4d001e8f7a23
+        files:
+          type: array
+          minItems: 1
+          description: Files to initiate. Each entry is validated and reserved independently.
+          items:
+            $ref: '#/components/schemas/UploadRequestFile'
+    PartUrl:
+      type: object
+      description: A presigned URL for uploading one part of a multipart upload.
+      required:
+        - partNumber
+        - url
+      properties:
+        partNumber:
+          type: integer
+          minimum: 1
+          description: |-
+            1-based index of this part. Send it back as the S3 `partNumber`
+            when uploading, and keep each part's returned `ETag` to finalize
+            the upload.
+          examples:
+            - 6
+        url:
+          type: string
+          format: uri
+          description: Presigned S3 URL to PUT this part's bytes to.
+          examples:
+            - https://integrator-file-storage.s3.us-west-2.amazonaws.com/...
+    UploadBody:
+      type: object
+      description: |-
+        Presigned-URL instructions for one file. The fields present depend on
+        `uploadType`: a single PUT returns one `uploadUrl`; a multipart upload
+        returns an `uploadId`, a batch of `partUrls`, and a `completeUrl`.
+      required:
+        - uploadType
+      properties:
+        uploadType:
+          type: string
+          enum:
+            - single
+            - multipart
+          x-enumDescriptions:
+            single: One presigned PUT for the whole file. Used for files up to 5 GB.
+            multipart: Per-part presigned PUTs plus a complete URL. Required beyond 5 GB.
+          description: Transfer mechanism the caller must use for this file.
+        uploadUrl:
+          type: string
+          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.
+          examples:
+            - https://integrator-file-storage.s3.us-west-2.amazonaws.com/...
+        uploadId:
+          type: string
+          description: |-
+            S3 multipart upload identifier. Present when uploadType is
+            multipart. Pass it to refresh-urls to fetch later part batches and
+            to cancel the upload.
+          examples:
+            - abcD12efGHIjklMN3opQrst
+        partUrls:
+          type: array
+          description: |-
+            Presigned URLs for the next batch of parts. Present when uploadType
+            is multipart. A request may return fewer parts than requested when
+            the account-wide part budget is constrained; fetch the remaining
+            parts with refresh-urls.
+          items:
+            $ref: '#/components/schemas/PartUrl'
+        completeUrl:
+          type: string
+          format: uri
+          description: |-
+            Presigned URL to POST the ordered list of part numbers and ETags to,
+            finalizing the multipart upload. Present when uploadType is multipart.
+          examples:
+            - https://integrator-file-storage.s3.us-west-2.amazonaws.com/...
+    UploadError:
+      type: object
+      description: A per-file failure within a batch upload response.
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: string
+          description: Machine-readable storage error code.
+          examples:
+            - STORAGE_INVALID_MIME_TYPE
+        message:
+          type: string
+          description: Human-readable explanation of the failure.
+          examples:
+            - Invalid MIME type
+    UploadResult:
+      type: object
+      description: |-
+        Outcome for one file in an upload response. On success, `statusCode` is
+        200 and `body` carries the presigned-URL instructions; on failure,
+        `statusCode` is a 4xx and `errors` explains why. Each file in a batch is
+        validated independently, so a single response can mix successes and
+        failures.
+      required:
+        - name
+        - statusCode
+      properties:
+        _id:
+          type: string
+          format: objectId
+          x-celigo-refModel: storageitems
+          description: |-
+            ID of the pending item this result refers to. Present once the item
+            is created; absent when the file failed validation before creation.
+            Use it to upload, refresh URLs, cancel, or download once active.
+          examples:
+            - 683b2a0e1c3d5f001a9e8b01
+        name:
+          type: string
+          description: File name echoed back from the request, to correlate results.
+          examples:
+            - logo.png
+        statusCode:
+          type: integer
+          description: Per-file result status, mirroring HTTP status semantics.
+          examples:
+            - 200
+        body:
+          $ref: '#/components/schemas/UploadBody'
+        errors:
+          type: array
+          description: Reasons the file was rejected. Present when statusCode is a 4xx.
+          items:
+            $ref: '#/components/schemas/UploadError'
+    InitiateUploadResponse:
+      type: object
+      description: Per-file upload instructions, in the same order as the request.
+      required:
+        - files
+      properties:
+        files:
+          type: array
+          items:
+            $ref: '#/components/schemas/UploadResult'
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    RefreshUrlsRequest:
+      type: object
+      description: Reissues presigned URLs for pending uploads whose URLs have expired.
+      required:
+        - items
+      properties:
+        items:
+          type: array
+          minItems: 1
+          description: Pending uploads to refresh. Each is processed independently.
+          items:
+            type: object
+            required:
+              - _id
+              - uploadType
+            properties:
+              _id:
+                type: string
+                format: objectId
+                x-celigo-refModel: storageitems
+                description: Pending item to reissue URLs for.
+                examples:
+                  - 683b2a0e1c3d5f001a9e8b03
+              uploadType:
+                type: string
+                enum:
+                  - single
+                  - multipart
+                x-enumDescriptions:
+                  single: Reissue the single PUT URL.
+                  multipart: Reissue URLs for the part numbers in `partNumbers`.
+                description: Must match the upload type the item was initiated with.
+              uploadId:
+                type: string
+                description: S3 multipart upload ID. Required when uploadType is multipart.
+                examples:
+                  - abcD12efGHIjklMN3opQrst
+              partNumbers:
+                type: array
+                description: |-
+                  Part numbers to reissue URLs for. Required when uploadType is
+                  multipart. Must continue sequentially after the last issued
+                  batch. Already-uploaded parts are preserved.
+                items:
+                  type: integer
+                  minimum: 1
+                examples:
+                  - - 3
+                    - 4
+                    - 5
+    RefreshUrlsResponse:
+      type: object
+      description: Per-item refreshed upload instructions.
+      required:
+        - items
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/UploadResult'
+    StorageItem:
+      type: object
+      description: A file or folder stored in Celigo Storage.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: storageitems
+          description: |-
+            Unique identifier for the item. Pass it to download, move, copy,
+            replace, rename, or delete the item; folders and files share one
+            ID space.
+          examples:
+            - 683b2a0e1c3d5f001a9e8b01
+        type:
+          type: string
+          enum:
+            - file
+            - folder
+          readOnly: true
+          x-enumDescriptions:
+            file: A content-bearing object backed by storage and counted against quota.
+            folder: An organizational container with no content and no storage cost.
+          description: |-
+            Distinguishes a content-bearing file from an organizational folder.
+            Fixed when the item is created and never changes.
+        name:
+          type: string
+          maxLength: 256
+          description: |-
+            Display name, including the extension for files (for example
+            `orders.csv`). Two items with the same name can coexist in one
+            folder — the name is not a unique key.
+          examples:
+            - logo.png
+        _parentId:
+          type:
+            - string
+            - 'null'
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: storageitems
+          description: |-
+            Folder that contains this item. Null when the item sits at the
+            account root.
+          examples:
+            - 683a1f2e9b0c4d001e8f7a23
+        __ancestorIds:
+          type: array
+          readOnly: true
+          description: |-
+            Folder IDs from the root down to the immediate parent, in order.
+            Empty for root-level items. Rewritten automatically when the item
+            or any ancestor folder is moved.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: storageitems
+          examples:
+            - - 683a1f2e9b0c4d001e8f7a23
+        size:
+          type: integer
+          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.
+          examples:
+            - 245760
+        mimeType:
+          type: string
+          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.
+          examples:
+            - image/png
+        description:
+          type: string
+          maxLength: 1000
+          description: Optional caller-supplied note describing the item.
+          examples:
+            - Quarterly financial reports
+        status:
+          type: string
+          enum:
+            - pending
+            - active
+          readOnly: true
+          x-enumDescriptions:
+            pending: Upload reserved but not yet finalized; the file cannot be downloaded, moved, or copied.
+            active: Fully uploaded and usable. Folders are always active.
+          description: |-
+            Upload lifecycle state. A file is created pending at initiate-upload
+            and flips to active once S3 confirms the bytes; folders are created
+            active.
+        isSystem:
+          type: boolean
+          readOnly: true
+          description: |-
+            When true, the platform created the item (for example a system or
+            integration folder) and protects it — move, content replace, copy,
+            delete, and purge are rejected with `STORAGE_SYSTEM_ITEM_PROTECTED`.
+        deletedAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: |-
+            Timestamp when the item was soft-deleted to the recycle bin. Present
+            only for recycle-bin items; the item is permanently purged 30 days
+            after this time unless restored.
+          examples:
+            - '2026-04-27T10:00:00.000Z'
+        deletedBy:
+          type: string
+          readOnly: true
+          description: |-
+            Who soft-deleted the item — a user ID for a direct delete, or
+            `cascadeDelete` for a descendant removed when its parent folder was
+            deleted. Present only for recycle-bin items. Cascade-deleted items
+            can be recovered only by restoring the folder that was deleted
+            directly.
+          examples:
+            - 60a1b2c3d4e5f6001a2b3c4d
+        location:
+          type: object
+          readOnly: true
+          description: |-
+            Folder that contains this search hit. Present only in search-mode
+            results from `GET /v1/storage/items` (when the `search` query
+            parameter is set).
+          properties:
+            _id:
+              type: string
+              format: objectId
+              x-celigo-refModel: storageitems
+              description: ID of the containing folder.
+              examples:
+                - 683a1f2e9b0c4d001e8f7a23
+            name:
+              type: string
+              description: Name of the containing folder.
+              examples:
+                - My Files
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the item was created.
+          examples:
+            - '2026-03-28T09:00:00.000Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: |-
+            Timestamp of the most recent metadata change. Updated on rename,
+            move, and content replace, and when the folder's direct children
+            change.
+          examples:
+            - '2026-03-28T14:30:00.000Z'
+      required:
+        - _id
+        - type
+        - name
+        - status
+        - isSystem
+        - createdAt
+        - lastModified
+    CreateFolderRequest:
+      type: object
+      description: Request body for creating a folder.
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          maxLength: 256
+          description: Folder name. Duplicate names within the same parent are allowed.
+          examples:
+            - Reports
+        _parentId:
+          type:
+            - string
+            - 'null'
+          format: objectId
+          x-celigo-refModel: storageitems
+          description: |-
+            Parent folder to create this folder in. Omit or pass null to create
+            it at the account root. Must reference an existing active folder.
+          examples:
+            - 683a1f2e9b0c4d001e8f7a23
+        description:
+          type: string
+          maxLength: 1000
+          description: Optional note describing the folder.
+          examples:
+            - Quarterly financial reports
+    BulkMoveResults:
+      type: object
+      description: Per-id move results, one entry per source id.
+      properties:
+        results:
+          type: array
+          items:
+            type: object
+            required:
+              - _id
+              - status
+            properties:
+              _id:
+                type: string
+                format: objectId
+                x-celigo-refModel: storageitems
+                description: Source item id this entry corresponds to.
+              status:
+                type: string
+                enum:
+                  - success
+                  - error
+                x-enumDescriptions:
+                  success: The item was moved.
+                  error: The item failed to move; see `errorCode` and `message`.
+                description: Outcome for this item.
+              _parentId:
+                type:
+                  - string
+                  - 'null'
+                format: objectId
+                x-celigo-refModel: storageitems
+                description: New parent folder (null for the root). Present on success.
+              __ancestorIds:
+                type: array
+                description: New ancestor chain from the root. Present on success.
+                items:
+                  type: string
+                  format: objectId
+                  x-celigo-refModel: storageitems
+              type:
+                type: string
+                enum:
+                  - file
+                  - folder
+                x-enumDescriptions:
+                  file: The moved item is a file.
+                  folder: The moved item is a folder (descendants re-anchor asynchronously).
+                description: Type of the moved item. Present on success.
+              errorCode:
+                type: string
+                description: Error code for this item. Present on error.
+              message:
+                type: string
+                description: Human-readable failure reason. Present on error.
+    UpdateRequest:
+      type: object
+      description: |-
+        Request body for renaming an item or changing its description. Provide
+        `name`, `description`, or both. Folder placement is changed with the move
+        endpoint, not here — `_parentId` and `__ancestorIds` are rejected.
+      properties:
+        name:
+          type: string
+          maxLength: 256
+          description: New display name for the item.
+          examples:
+            - quarterly-report-final.pdf
+        description:
+          type: string
+          maxLength: 1000
+          description: New description. Pass an empty string to clear it.
+          examples:
+            - Updated Q1 2026 financial report
+    ReplaceRequest:
+      type: object
+      description: |-
+        Requests presigned URLs to overwrite an existing file's content in place.
+        Same shape as one initiate-upload file entry, minus `name` — the existing
+        name, `_id`, and folder placement are preserved. Rename with
+        `PUT /v1/storage/items/{_id}` instead.
+      required:
+        - uploadType
+      properties:
+        mimeType:
+          type: string
+          maxLength: 256
+          description: |-
+            New media type for the replaced content. Optional; the existing
+            mimeType is kept when omitted.
+          examples:
+            - application/pdf
+        size:
+          type: integer
+          format: int64
+          minimum: 0
+          description: |-
+            Declared size in bytes of the replacement content, used to reserve
+            quota. Reconciled to the real size when the upload finalizes.
+          examples:
+            - 5242880
+        uploadType:
+          type: string
+          enum:
+            - single
+            - multipart
+          x-enumDescriptions:
+            single: One presigned PUT for the whole file. Use for content up to 5 GB.
+            multipart: Chunked upload with per-part URLs. Required beyond 5 GB.
+          description: How the replacement content will be transferred.
+        numParts:
+          type: integer
+          minimum: 1
+          description: Number of parts the replacement will be split into. Required when uploadType is multipart.
+          examples:
+            - 5
+        uploadId:
+          type: string
+          description: |-
+            S3 multipart upload ID from a prior replace response. Provide with
+            `issuedPartsCount` to resume and request the next batch of part URLs.
+          examples:
+            - abcD12efGHIjklMN3opQrst
+        issuedPartsCount:
+          type: integer
+          minimum: 0
+          description: |-
+            Number of part URLs already issued. Provide together with `uploadId`
+            to resume an in-progress replacement.
+          examples:
+            - 5
+    MergeRequest:
+      type: object
+      description: Request body for merging a folder into another folder.
+      required:
+        - _destinationId
+      properties:
+        _destinationId:
+          type: string
+          format: objectId
+          x-celigo-refModel: storageitems
+          description: |-
+            Destination folder that receives the source folder's contents. Must
+            reference an existing active folder that is different from the source
+            and not one of its descendants.
+          examples:
+            - 6a6e1d9e7042f856e8d731ab
+        trigger:
+          type: string
+          enum:
+            - move
+            - rename
+          default: move
+          x-enumDescriptions:
+            move: Record the merge as a move operation.
+            rename: Record the merge as a rename operation.
+          description: |-
+            How the merge is recorded. Unrecognized values fall back to `move`.
+            Ignored when the source folder is soft-deleted — the platform then
+            records the merge as a restore automatically.
+    MoveRequest:
+      type: object
+      description: Request body for moving an item to a different folder.
+      required:
+        - _parentId
+      properties:
+        _parentId:
+          type:
+            - string
+            - 'null'
+          format: objectId
+          x-celigo-refModel: storageitems
+          description: |-
+            Destination folder. Pass null to move the item to the account root.
+            The key is required even when null. Must differ from the current
+            parent, must be an active folder, and — for a folder — must not be
+            the item itself or one of its descendants.
+          examples:
+            - 684c3b1f2d4e6g002b0h9c34
+    CopyRequest:
+      type: object
+      description: Request body for copying a file.
+      properties:
+        _destinationId:
+          type:
+            - string
+            - 'null'
+          format: objectId
+          x-celigo-refModel: storageitems
+          description: |-
+            Destination folder for the copy. Pass null to copy to the account
+            root. Must reference an existing active folder.
+          examples:
+            - 684c3b1f2d4e6g002b0h9c34
+        name:
+          type: string
+          maxLength: 256
+          description: |-
+            Name for the copy. Defaults to the source file's name when omitted.
+            Duplicate names are allowed, so a copy into the source's own folder
+            with no name produces a second file with the same name.
+          examples:
+            - quarterly-report-copy.pdf
+    DependencyEntry:
+      type: object
+      description: A single resource that depends on the queried resource.
+      properties:
+        id:
+          type: string
+          description: Unique identifier of the dependent resource.
+          examples:
+            - 61f92026dd053843b5d72350
+        name:
+          type: string
+          description: Display name of the dependent resource.
+          examples:
+            - Import Orders to NetSuite
+        paths:
+          type: array
+          description: |-
+            Dot-notation paths within the dependent resource that reference
+            the target resource. `[*]` denotes array elements.
+          items:
+            type: string
+          examples:
+            - - hooks.preSavePage._scriptId
+        accessLevel:
+          type: string
+          description: The caller's access level on the dependent resource.
+          examples:
+            - manage
+        dependencyIds:
+          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:
+              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
+    Usage:
+      type: object
+      description: Account-wide storage usage and entitlement, aggregated across all environments.
+      required:
+        - activeUsage
+        - recycleBinUsage
+        - totalUsage
+        - maxAllowedUsage
+        - isOverage
+        - hardLimit
+        - overage
+      properties:
+        activeUsage:
+          type: integer
+          format: int64
+          description: Bytes consumed by active and pending files.
+          examples:
+            - 536870912
+        recycleBinUsage:
+          type: integer
+          format: int64
+          description: Bytes consumed by soft-deleted files still retained in the recycle bin.
+          examples:
+            - 104857600
+        totalUsage:
+          type: integer
+          format: int64
+          description: |-
+            Sum of activeUsage and recycleBinUsage. This is the figure checked
+            against hardLimit when an upload is attempted.
+          examples:
+            - 641728512
+        systemUsage:
+          type: integer
+          format: int64
+          description: |-
+            Bytes consumed by system items (folders and files the platform
+            created). Present only when the request sets `includeSystem=true`.
+          examples:
+            - 52428800
+        maxAllowedUsage:
+          type: integer
+          format: int64
+          description: Storage quota in bytes granted by the account's license.
+          examples:
+            - 1073741824
+        isOverage:
+          type: boolean
+          description: |-
+            When true, totalUsage has passed maxAllowedUsage and the account is
+            consuming the overage buffer. Uploads still succeed until totalUsage
+            reaches hardLimit.
+        hardLimit:
+          type: integer
+          format: int64
+          description: |-
+            Byte ceiling at which further uploads are rejected with
+            `STORAGE_QUOTA_EXCEEDED`. Equals maxAllowedUsage plus the licensed
+            overage buffer, or maxAllowedUsage exactly when overage is disabled.
+          examples:
+            - 1288490188
+        overage:
+          type: integer
+          format: int64
+          description: Bytes currently consumed beyond maxAllowedUsage. Zero when not in overage.
+          examples:
+            - 0
+    EnvironmentUsage:
+      type: object
+      description: Storage usage for a single environment.
+      required:
+        - _envUserId
+        - activeUsage
+        - recycleBinUsage
+        - totalUsage
+      properties:
+        _envUserId:
+          type: string
+          format: objectId
+          description: Environment user ID this breakdown belongs to.
+          examples:
+            - 60a1b2c3d4e5f6001a2b3c4d
+        name:
+          type: string
+          description: Environment name, such as Production or Sandbox.
+          examples:
+            - Production
+        activeUsage:
+          type: integer
+          format: int64
+          description: Bytes consumed by active and pending files in this environment.
+          examples:
+            - 429496729
+        recycleBinUsage:
+          type: integer
+          format: int64
+          description: Bytes consumed by this environment's soft-deleted files.
+          examples:
+            - 52428800
+        totalUsage:
+          type: integer
+          format: int64
+          description: Sum of this environment's activeUsage and recycleBinUsage.
+          examples:
+            - 481925529
+    UsageEnvironments:
+      type: object
+      description: |-
+        Per-environment usage breakdown alongside the same account-wide totals
+        returned by `GET /v1/storage/usage`.
+      required:
+        - environments
+        - activeUsage
+        - recycleBinUsage
+        - totalUsage
+        - maxAllowedUsage
+        - isOverage
+        - hardLimit
+        - overage
+      properties:
+        environments:
+          type: array
+          description: One entry per environment in the account.
+          items:
+            $ref: '#/components/schemas/EnvironmentUsage'
+        activeUsage:
+          type: integer
+          format: int64
+          description: Account-wide bytes consumed by active and pending files.
+          examples:
+            - 536870912
+        recycleBinUsage:
+          type: integer
+          format: int64
+          description: Account-wide bytes consumed by soft-deleted files.
+          examples:
+            - 104857600
+        totalUsage:
+          type: integer
+          format: int64
+          description: Account-wide sum of activeUsage and recycleBinUsage.
+          examples:
+            - 641728512
+        systemUsage:
+          type: integer
+          format: int64
+          description: |-
+            Account-wide bytes consumed by system items. Present only when the
+            request sets `includeSystem=true`.
+          examples:
+            - 52428800
+        maxAllowedUsage:
+          type: integer
+          format: int64
+          description: Storage quota in bytes granted by the account's license.
+          examples:
+            - 1073741824
+        isOverage:
+          type: boolean
+          description: When true, totalUsage has passed maxAllowedUsage and the account is in the overage buffer.
+        hardLimit:
+          type: integer
+          format: int64
+          description: Byte ceiling at which further uploads are rejected.
+          examples:
+            - 1288490188
+        overage:
+          type: integer
+          format: int64
+          description: Bytes currently consumed beyond maxAllowedUsage. Zero when not in overage.
+          examples:
+            - 0
+  responses:
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    403-forbidden:
+      description: |
+        Forbidden. The authenticated caller does not have permission to perform this operation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+x-internal: false
+x-enable-proxy: true