@celigo/api-specs 0.2.92 → 0.2.94

package/dist/filestorage.yml

@@ -17,7 +17,7 @@ security:
 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.
+      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, where names are unique among live items; renames and moves keep the `_id` stable, and deletes go to a 30-day recycle bin before they can be purged.
 
       ## Storage item schema
 
@@ -35,10 +35,14 @@ paths:
         to those URLs — a single PUT must carry the
         `x-amz-server-side-encryption: AES256` header — then the item flips to
         active once S3 confirms it; no further API call is needed. Each URL's
-        lifetime is in its `X-Amz-Expires` parameter; reissue expired URLs with
-        `POST /v1/storage/files/refresh-urls`. Each file is validated
-        independently, so the response can mix per-file successes and failures
-        while the request itself returns 200.
+        lifetime is in its `X-Amz-Expires` parameter; once every part already
+        issued has been uploaded, a multipart upload fetches further part URLs by
+        posting again with the item's `_id`, `uploadId`, and `issuedPartsCount`,
+        while an expired single PUT URL cannot be reissued.
+        Each file is validated independently, so the response can mix per-file
+        successes and failures while the request itself returns 200 — a name
+        already held by a live item in the target folder fails that entry with
+        409 `STORAGE_ITEM_ALREADY_EXISTS`.
       operationId: initiateStorageUpload
       tags:
         - File Storage
@@ -86,7 +90,7 @@ paths:
                 $ref: '#/components/schemas/InitiateUploadResponse'
               examples:
                 mixed:
-                  summary: Single success, multipart success, and a rejection
+                  summary: Single success, multipart success, and two rejections
                   value:
                     files:
                       - _id: 683b2a0e1c3d5f001a9e8b01
@@ -112,70 +116,11 @@ paths:
                         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 (each URL's lifetime is in its `X-Amz-Expires` parameter). For a
-        single PUT, returns a fresh upload URL; for multipart, returns fresh URLs
-        for the requested part numbers plus the complete URL. Already-uploaded
-        parts are preserved. Each item is processed independently.
-      operationId: refreshStorageUploadUrls
-      tags:
-        - File Storage
-      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
+                      - name: orders.csv
+                        statusCode: 409
+                        errors:
+                          - code: STORAGE_ITEM_ALREADY_EXISTS
+                            message: An item named "orders.csv" already exists in this folder
         '400':
           $ref: '#/components/responses/400-bad-request'
         '401':
@@ -406,7 +351,9 @@ paths:
           required: false
           description: |-
             Folder whose direct children to list. Omit for the account root.
-            Ignored in search mode.
+            Ignored in search mode. An id that names no item answers 404
+            `STORAGE_PARENT_NOT_FOUND`; a file's id answers 422
+            `STORAGE_PARENT_NOT_FOLDER`.
           schema:
             type: string
             format: objectId
@@ -721,16 +668,41 @@ paths:
         '403':
           $ref: '#/components/responses/403-forbidden'
         '404':
-          $ref: '#/components/responses/404-not-found'
+          description: |-
+            `_parentId` names no item in the account. Error code:
+            `STORAGE_PARENT_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                parentNotFound:
+                  value:
+                    errors:
+                      - code: STORAGE_PARENT_NOT_FOUND
+                        message: Parent folder not found
         '422':
           description: |-
             A filter is malformed or two filters that cannot be combined were
-            sent together. Error code: `STORAGE_INVALID_FILTER`.
+            sent together (`STORAGE_INVALID_FILTER`), or `_parentId` is a file
+            rather than a folder (`STORAGE_PARENT_NOT_FOLDER`).
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
               examples:
+                parentNotFolder:
+                  summary: _parentId is a file
+                  value:
+                    errors:
+                      - code: STORAGE_PARENT_NOT_FOLDER
+                        message: Parent must be a folder
+                invalidParentId:
+                  summary: _parentId is not an ObjectId
+                  value:
+                    errors:
+                      - code: STORAGE_INVALID_FILTER
+                        message: _parentId must be a valid ObjectId
                 invalidMimeType:
                   summary: Media type is not a valid type/subtype pair
                   value:
@@ -755,7 +727,9 @@ paths:
       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`.
+        `POST /v1/storage/files/initiateUpload`. A name already held by a live
+        file or folder in the parent is rejected with 409
+        `STORAGE_ITEM_ALREADY_EXISTS`.
       operationId: createStorageFolder
       tags:
         - File Storage
@@ -808,6 +782,20 @@ paths:
           $ref: '#/components/responses/403-forbidden'
         '404':
           $ref: '#/components/responses/404-not-found'
+        '409':
+          description: |-
+            A live file or folder with this name already exists in the parent.
+            Error code: `STORAGE_ITEM_ALREADY_EXISTS`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                nameTaken:
+                  value:
+                    errors:
+                      - code: STORAGE_ITEM_ALREADY_EXISTS
+                        message: An item named "Reports" already exists in this folder
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
   /v1/storage/items/batch:
@@ -1099,7 +1087,8 @@ paths:
         '207':
           description: |-
             Mixed results — at least one item failed to move. Inspect each
-            entry's `status`.
+            entry's `status`; a destination name collision reports
+            `STORAGE_ITEM_ALREADY_EXISTS` on that entry while the others proceed.
           content:
             application/json:
               schema:
@@ -1118,6 +1107,10 @@ paths:
                         status: error
                         errorCode: STORAGE_MOVE_SAME_PARENT_DISALLOWED
                         message: The item is already in the destination folder
+                      - _id: 683b2a0e1c3d5f001a9e8b05
+                        status: error
+                        errorCode: STORAGE_ITEM_ALREADY_EXISTS
+                        message: An item named "Reports" already exists in this folder
         '400':
           description: |-
             Malformed request — `_parentFolderId` key missing
@@ -1272,9 +1265,10 @@ paths:
       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`.
+        survive; a name already held by another live item in the same folder is
+        rejected with 409 `STORAGE_ITEM_ALREADY_EXISTS`. To move an item to a
+        different folder, use `PATCH /v1/storage/items/{_id}/move`; to replace a
+        file's content, use `PATCH /v1/storage/items/{_id}/replace`.
       operationId: updateStorageItem
       tags:
         - File Storage
@@ -1334,6 +1328,20 @@ paths:
           $ref: '#/components/responses/403-forbidden'
         '404':
           $ref: '#/components/responses/404-not-found'
+        '409':
+          description: |-
+            Another live item in the same folder already has the requested
+            `name` (`STORAGE_ITEM_ALREADY_EXISTS`). Nothing was changed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                nameTaken:
+                  value:
+                    errors:
+                      - code: STORAGE_ITEM_ALREADY_EXISTS
+                        message: An item named "quarterly-report-final.pdf" already exists in this folder
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
     delete:
@@ -1344,10 +1352,16 @@ paths:
         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,
+        follow asynchronously. Delete is not blocked by references — flows,
         exports, imports, and tokens that point at the item are left dangling and
-        fail at runtime. A pending multipart upload cannot be deleted here —
-        cancel it with `POST /v1/storage/files/{_id}/cancel`.
+        fail at runtime — with one exception: a folder that is, or contains, the
+        home folder of a File Server account answers 403
+        `STORAGE_SFTP_HOME_FOLDER_PROTECTED` until that account is deleted or moved
+        to another folder (`/v1/mft/fileserver/accounts`). Renaming or moving such
+        a folder is still allowed. A pending multipart upload cannot be deleted
+        here — cancel it with `POST /v1/storage/files/{_id}/cancel`. A pending
+        single PUT upload whose presigned URL is still live is refused with 403
+        `STORAGE_PRESIGNED_URL_ACTIVE`; retry after the URL expires.
       operationId: deleteStorageItem
       tags:
         - File Storage
@@ -1370,7 +1384,30 @@ paths:
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
-          $ref: '#/components/responses/403-forbidden'
+          description: |-
+            The caller lacks permission for this item; the folder is (or
+            contains) a File Server account's home folder
+            (`STORAGE_SFTP_HOME_FOLDER_PROTECTED` — delete or move the account
+            first); or the item is a pending single PUT upload whose presigned
+            URL has not expired yet (`STORAGE_PRESIGNED_URL_ACTIVE` — the upload
+            may still be in flight, so retry once the URL's lifetime has passed).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                sftpHomeFolder:
+                  summary: Folder is in use as an SFTP home folder
+                  value:
+                    errors:
+                      - code: STORAGE_SFTP_HOME_FOLDER_PROTECTED
+                        message: This folder cannot be deleted because it is in use as an SFTP home folder
+                presignedUrlActive:
+                  summary: Pending single PUT upload with a live URL
+                  value:
+                    errors:
+                      - code: STORAGE_PRESIGNED_URL_ACTIVE
+                        message: Presigned upload URL is still active; retry after it expires
         '404':
           $ref: '#/components/responses/404-not-found'
         '422':
@@ -1628,7 +1665,10 @@ paths:
         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.
+        own descendants. A destination that already holds a live item with the
+        same name rejects the move with 409 `STORAGE_ITEM_ALREADY_EXISTS` — send
+        `name` to land beside it, or fold a folder into its namesake with
+        `POST /v1/storage/items/{_id}/merge`.
       operationId: moveStorageItem
       tags:
         - File Storage
@@ -1734,6 +1774,21 @@ paths:
           $ref: '#/components/responses/403-forbidden'
         '404':
           $ref: '#/components/responses/404-not-found'
+        '409':
+          description: |-
+            The destination already holds a live item with the moved item's
+            name — or with the `name` sent (`STORAGE_ITEM_ALREADY_EXISTS`).
+            Nothing was moved.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                nameTaken:
+                  value:
+                    errors:
+                      - code: STORAGE_ITEM_ALREADY_EXISTS
+                        message: An item named "inv-001.pdf" already exists in this folder
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
   /v1/storage/items/{_id}/copy:
@@ -1741,11 +1796,12 @@ paths:
       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.
+        Creates an independent copy of a file in the folder named by `_parentId`,
+        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.
+        Without `name` the copy is called `Clone - ` followed by the source
+        file's name; a name already held by a live item in the destination is
+        rejected with 409 `STORAGE_ITEM_ALREADY_EXISTS`.
       operationId: copyStorageFile
       tags:
         - File Storage
@@ -1770,12 +1826,12 @@ paths:
               rename:
                 summary: Copy into a folder with a new name
                 value:
-                  _destinationId: 684c3b1f2d4e6g002b0h9c34
+                  _parentId: 684c3b1f2d4e6g002b0h9c34
                   name: quarterly-report-copy.pdf
               toRoot:
-                summary: Copy to the account root, keeping the name
+                summary: Copy to the account root as "Clone - <source name>"
                 value:
-                  _destinationId: null
+                  _parentId: null
       responses:
         '201':
           description: The newly created copy.
@@ -1809,6 +1865,20 @@ paths:
           $ref: '#/components/responses/403-forbidden'
         '404':
           $ref: '#/components/responses/404-not-found'
+        '409':
+          description: |-
+            A live item with the copy's name already exists in the destination
+            (`STORAGE_ITEM_ALREADY_EXISTS`). Retry with a different `name`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                nameTaken:
+                  value:
+                    errors:
+                      - code: STORAGE_ITEM_ALREADY_EXISTS
+                        message: An item named "Clone - quarterly-report.pdf" already exists in this folder
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
   /v1/storage/items/{_id}/restore:
@@ -1821,7 +1891,9 @@ paths:
         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.
+        parent folder is restored. If a live item has taken the name in the
+        original folder since the delete, the restore is rejected with 409
+        `STORAGE_ITEM_ALREADY_EXISTS`; send `name` to restore under a new one.
       operationId: restoreStorageItem
       tags:
         - File Storage
@@ -1836,17 +1908,67 @@ paths:
             x-celigo-refModel: storageitems
             examples:
               - 683b2a0e1c3d5f001a9e8b01
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RestoreRequest'
+            examples:
+              keepName:
+                summary: Restore under the original name
+                value: {}
+              rename:
+                summary: Restore under a new name because the original is taken
+                value:
+                  name: inv-001 (restored).pdf
       responses:
-        '204':
+        '200':
           description: |-
-            Item restored. For a folder, the root is restored and its descendants
-            follow asynchronously.
+            The restored item. For a folder, the root is restored and its
+            descendants follow asynchronously.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StorageItem'
+              examples:
+                default:
+                  value:
+                    _id: 683b2a0e1c3d5f001a9e8b01
+                    _userId: 624cb0346309dc3a543733a2
+                    _parentId: 683a1f2e9b0c4d001e8f7a23
+                    __ancestorIds:
+                      - 683a1f2e9b0c4d001e8f7a23
+                    _integrationId: null
+                    type: file
+                    name: inv-001 (restored).pdf
+                    size: 245760
+                    mimeType: application/pdf
+                    status: active
+                    isSystem: false
+                    createdAt: '2026-03-28T10:00:00.000Z'
+                    lastModified: '2026-04-28T09:15:00.000Z'
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
           $ref: '#/components/responses/403-forbidden'
         '404':
           $ref: '#/components/responses/404-not-found'
+        '409':
+          description: |-
+            A live item in the original folder already has the item's name — or
+            the `name` sent (`STORAGE_ITEM_ALREADY_EXISTS`). The item stays in
+            the recycle bin.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                nameTaken:
+                  value:
+                    errors:
+                      - code: STORAGE_ITEM_ALREADY_EXISTS
+                        message: An item named "inv-001.pdf" already exists in this folder
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
   /v1/storage/items/{_id}/purge:
@@ -2250,7 +2372,11 @@ components:
         name:
           type: string
           maxLength: 256
-          description: File name, including extension. Duplicate names in a folder are allowed.
+          description: |-
+            File name, including extension. Must not match a live file or folder
+            in the target folder (case-sensitive; a pending upload already holds
+            its name), or the entry fails with 409 `STORAGE_ITEM_ALREADY_EXISTS`
+            while the rest of the batch proceeds.
           examples:
             - logo.png
         mimeType:
@@ -2382,8 +2508,10 @@ components:
             Present when uploadType is single. The PUT must carry the header
             `x-amz-server-side-encryption: AES256` — it is part of the signature,
             and S3 rejects the upload with 403 `SignatureDoesNotMatch` without
-            it. The URL's `X-Amz-Expires` parameter carries its lifetime; use
-            `POST /v1/storage/files/refresh-urls` to reissue an expired one.
+            it. The URL's `X-Amz-Expires` parameter carries its lifetime and
+            there is no endpoint to reissue it: an expired single PUT means
+            starting a new upload. While the URL is live the pending item holds
+            its name and cannot be deleted (`STORAGE_PRESIGNED_URL_ACTIVE`).
           examples:
             - https://integrator-file-storage.s3.us-west-2.amazonaws.com/...
           x-celigo-ai-guidance:
@@ -2392,8 +2520,9 @@ components:
           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.
+            multipart. Send it back to `POST /v1/storage/files/initiateUpload`
+            with the item's `_id` and `issuedPartsCount` to fetch the next batch
+            of part URLs once every part already issued has been uploaded.
           examples:
             - abcD12efGHIjklMN3opQrst
         partUrls:
@@ -2401,8 +2530,11 @@ components:
           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.
+            the account-wide part budget is constrained; after uploading every
+            part in this batch, fetch the remaining parts by posting to
+            initiateUpload again with the item's `_id`, `uploadId`, and
+            `issuedPartsCount` — before then the entry fails with
+            `STORAGE_PARTS_MISMATCH`.
           items:
             $ref: '#/components/schemas/PartUrl'
         completeUrl:
@@ -2449,7 +2581,8 @@ components:
           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.
+            Use it to continue a multipart upload, cancel it, or download the
+            file once active.
           examples:
             - 683b2a0e1c3d5f001a9e8b01
         name:
@@ -2519,66 +2652,6 @@ components:
               - 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.
@@ -2611,8 +2684,11 @@ components:
           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.
+            `orders.csv`). Unique among the live items of one folder: files and
+            folders share the namespace, matching is case-sensitive, and a
+            pending upload holds its name. Any write that would duplicate a name
+            is rejected with 409 `STORAGE_ITEM_ALREADY_EXISTS`; items in the
+            recycle bin release theirs.
           examples:
             - logo.png
         _userId:
@@ -2795,7 +2871,10 @@ components:
         name:
           type: string
           maxLength: 256
-          description: Folder name. Duplicate names within the same parent are allowed.
+          description: |-
+            Folder name. Must not match a live file or folder already in the
+            parent (case-sensitive); a duplicate is rejected with 409
+            `STORAGE_ITEM_ALREADY_EXISTS`.
           examples:
             - Reports
         _parentId:
@@ -2879,7 +2958,10 @@ components:
                 description: Type of the moved item. Present on success.
               errorCode:
                 type: string
-                description: Error code for this item. Present on error.
+                description: |-
+                  Error code for this item, such as `STORAGE_ITEM_ALREADY_EXISTS`
+                  when the destination already holds a live item with that name.
+                  Present on error.
               message:
                 type: string
                 description: Human-readable failure reason. Present on error.
@@ -2893,7 +2975,10 @@ components:
         name:
           type: string
           maxLength: 256
-          description: New display name for the item.
+          description: |-
+            New display name for the item. Must not match another live item in
+            the same folder (case-sensitive); a collision is rejected with 409
+            `STORAGE_ITEM_ALREADY_EXISTS`.
           examples:
             - quarterly-report-final.pdf
         description:
@@ -3020,7 +3105,7 @@ components:
       type: object
       description: Request body for copying a file.
       properties:
-        _destinationId:
+        _parentId:
           type:
             - string
             - 'null'
@@ -3028,18 +3113,37 @@ components:
           x-celigo-refModel: storageitems
           description: |-
             Destination folder for the copy. Pass null to copy to the account
-            root. Must reference an existing active folder.
+            root; omit it to copy into the source file's own folder. An id that
+            names no folder answers 404 `STORAGE_PARENT_NOT_FOUND`, and a file's
+            id 422 `STORAGE_PARENT_NOT_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.
+            Name for the copy. When omitted, the copy is called `Clone - `
+            followed by the source file's name. Must not match a live item in
+            the destination (case-sensitive): a collision is rejected with 409
+            `STORAGE_ITEM_ALREADY_EXISTS`, so a second unnamed copy into the
+            same folder needs an explicit name.
           examples:
             - quarterly-report-copy.pdf
+    RestoreRequest:
+      type: object
+      description: |-
+        Optional request body for restoring an item from the recycle bin. Send
+        an empty body or omit it to restore under the original name.
+      properties:
+        name:
+          type: string
+          maxLength: 256
+          description: |-
+            New name applied as the item comes back, so a name taken in its
+            original folder since the delete can be resolved in the same call.
+            Omit to keep the original name.
+          examples:
+            - inv-001 (restored).pdf
     StorageAuditEntry:
       type: object
       description: |-