@celigo/api-specs 0.2.92 → 0.2.93

package/dist/fileserver.yml

@@ -120,12 +120,14 @@ paths:
         Enables the environment's file server — creating it, and claiming the permanent
         `identifier`, on the first call — or disables it. The body must carry `enabled`
         as a JSON boolean; anything else is refused rather than interpreted, because a
-        disable ends every open partner session. Enabling also checks the environment's
-        Celigo Storage entitlement (partner uploads land there) and returns the current
-        `storageUsage` alongside the server. Disabling keeps the identifier and every
-        account, refuses new logins, and ends open sessions; repeating a disable is a
-        no-op. Sandbox environments cannot enable a server (403
-        `FILESERVER_NOT_ENTITLED`). Requires a full-access API token.
+        disable ends every open partner session. Every `enabled: true` call, including
+        one on a server that is already enabled, checks the account's Celigo Storage
+        entitlement (partner uploads land there) and returns the current `storageUsage`
+        alongside the server; `identifier` may be omitted once the server exists.
+        Disabling keeps the identifier and every account, refuses new logins, and ends
+        open sessions; repeating a disable is a no-op. Sandbox environments cannot
+        enable a server (403 `FILESERVER_NOT_ENTITLED`). Requires a full-access API
+        token.
       requestBody:
         required: true
         content:
@@ -138,18 +140,50 @@ paths:
                 value:
                   enabled: true
                   identifier: acme-logistics
+              reEnable:
+                summary: Repeat enable on an existing server — identifier omitted
+                value:
+                  enabled: true
               disable:
                 summary: Disable (identifier may be echoed, never changed)
                 value:
                   enabled: false
       responses:
         '200':
-          description: The server after the change. Includes `storageUsage` when the call enabled it.
+          description: 'The server after the change. Includes `storageUsage` whenever `enabled: true` was sent.'
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/FileServer'
               examples:
+                enabled:
+                  summary: Enabled server with the storage usage read at enable time
+                  value:
+                    _id: 6ab1ef197cf630a06d774cf1
+                    enabled: true
+                    identifier: acme-logistics
+                    endpoint:
+                      hostname: sftp.integrator.io
+                      port: 22
+                    hostKeyFingerprints:
+                      - algorithm: ssh-ed25519
+                        fingerprint: SHA256:iYC+28MNea2ebwWmUMdnJRx0StabV53gZBmr6pto9fs
+                      - algorithm: rsa-sha2-512
+                        fingerprint: SHA256:0Qy3l7fJ2Zb1n8VtY4cH6uWkPq9rS2dE5gL7mN1oT3A
+                    loginFormat: <username>@acme-logistics
+                    limits:
+                      maxAccounts: 1000
+                      maxConcurrentSessionsPerAccount: 20
+                      maxFileSizeBytes: 10737418240
+                    entitled: true
+                    storageUsage:
+                      activeUsage: 3387143
+                      recycleBinUsage: 26305326
+                      totalUsage: 29692469
+                      maxAllowedUsage: 214748364800
+                      isOverage: false
+                      hardLimit: 429496729600
+                      overage: 0
                 disabled:
                   summary: Disabled server
                   value:
@@ -272,18 +306,21 @@ paths:
       description: |-
         Returns the environment's partner accounts oldest first, wrapped in an
         `accounts` array, with `overCap` computed for each against the current
-        `limits.maxAccounts`. Paging is cursor-based: when more accounts follow, the
-        `Link` header carries a `rel="next"` URL whose `after` cursor (and `pageSize`)
-        fetch the next page, and a page reached through `after` also offers
-        `rel="prev"`. Cursors are opaque — pass them back exactly as received; anything
-        else answers 400 `FILESERVER_INVALID_CURSOR`. Accounts stay listable after the
-        add-on is removed from the license; only writes are blocked then. Requires a
-        full-access API token and a server that has been enabled at least once.
+        `limits.maxAccounts`. Paging is cursor-based through the `Link` header, which
+        lists bare absolute URLs separated by `, ` rather than RFC 8288 `<url>; rel=`
+        pairs: a URL carrying `after` (listed first) is present when more accounts
+        follow the page, and a URL carrying `before` is present when accounts precede
+        it — so the first page offers only `after`, the last page only `before`. The
+        header is absent when every account fits in one page. Cursors are opaque —
+        pass them back exactly as received; anything else answers 400
+        `FILESERVER_INVALID_CURSOR`. Accounts stay listable after the add-on is removed
+        from the license; only writes are blocked then. Requires a full-access API
+        token and a server that has been enabled at least once.
       parameters:
         - name: pageSize
           in: query
           required: false
-          description: Accounts per page. Values outside the range are clamped rather than rejected.
+          description: Accounts per page. Out-of-range and non-numeric values are not rejected — `0` and non-numbers fall back to the default.
           schema:
             type: integer
             minimum: 1
@@ -294,13 +331,13 @@ paths:
         - name: after
           in: query
           required: false
-          description: Opaque cursor from the previous page's `rel="next"` link. Returns the accounts created after it.
+          description: Opaque cursor copied from the `after` URL in the previous page's `Link` header. Returns the accounts created after it.
           schema:
             type: string
         - name: before
           in: query
           required: false
-          description: Opaque cursor from a page's `rel="prev"` link. Returns the accounts created before it. Ignored when `after` is also sent.
+          description: Opaque cursor copied from the `before` URL in a page's `Link` header. Returns the accounts created before it. Ignored when `after` is also sent.
           schema:
             type: string
       responses:
@@ -309,11 +346,15 @@ paths:
           headers:
             Link:
               description: |-
-                RFC 8288 pagination links: `<…?after=…&pageSize=…>; rel="next"` when more
-                accounts follow, `<…?before=…&pageSize=…>; rel="prev"` when the page was
-                reached through a cursor. Absent when the whole list fits in one page.
+                Pagination links as bare absolute URLs separated by `, ` — not the RFC 8288
+                `<url>; rel=` form. The URL carrying `after` (listed first) is present when
+                more accounts follow this page; the URL carrying `before` is present when
+                accounts precede it. Both repeat the request's `pageSize`. Absent when the
+                whole list fits in one page.
               schema:
                 type: string
+                examples:
+                  - https://api.integrator.io/v1/mft/fileserver/accounts?after=WyIyMDI2LTEwLTA3VDA2OjE5OjQzLjg4NloiLCI2YWM1ZTQ3ZjRhNzRiMzMzNDQxNzZkOTEiXQ&pageSize=100, https://api.integrator.io/v1/mft/fileserver/accounts?before=WyIyMDI2LTEwLTA3VDA2OjE5OjQzLjg4NloiLCI2YWM1ZTQ3ZjRhNzRiMzMzNDQxNzZkOTEiXQ&pageSize=100
           content:
             application/json:
               schema:
@@ -333,7 +374,7 @@ paths:
                         username: northwind-edi
                         login: northwind-edi@acme-logistics
                         _homeFolderId: 6ab1f25daa3e7ed226ea3f25
-                        homeFolderPath: Partners/Northwind/Inbound
+                        homeFolderPath: /Partners/Northwind/Inbound
                         enabled: true
                         passwordSet: true
                         overCap: false
@@ -389,9 +430,11 @@ paths:
         Celigo Storage home folder, and returns it (the password is never returned).
         Checks run in order and the first failure is answered: username shape, password
         presence, home-folder presence, the enabled-account cap, then the folder is
-        verified to be an active folder in this environment. Requires a full-access API
-        token, the file server add-on on the license, and a server that has been enabled
-        at least once.
+        verified to be an active folder in this environment. From then on the folder
+        and every folder above it refuse `DELETE /v1/storage/items/{_id}` with 403
+        `STORAGE_SFTP_HOME_FOLDER_PROTECTED` until the account is deleted or moved.
+        Requires a full-access API token, the file server add-on on the license, and a
+        server that has been enabled at least once.
       requestBody:
         required: true
         content:
@@ -418,7 +461,7 @@ paths:
                     username: northwind-edi
                     login: northwind-edi@acme-logistics
                     _homeFolderId: 6ab1f25daa3e7ed226ea3f25
-                    homeFolderPath: Partners/Northwind/Inbound
+                    homeFolderPath: /Partners/Northwind/Inbound
                     enabled: true
                     passwordSet: true
                     overCap: false
@@ -471,7 +514,8 @@ paths:
           description: |-
             The server has never been enabled (`FILESERVER_NOT_ENABLED`); `username` is
             missing or malformed (`FILESERVER_USERNAME_INVALID`); `password` is missing
-            (`FILESERVER_LAST_CREDENTIAL`) or too weak (`FILESERVER_WEAK_PASSWORD`);
+            or not a string (`FILESERVER_LAST_CREDENTIAL`) or too weak
+            (`FILESERVER_WEAK_PASSWORD` — the message lists every rule broken);
             `_homeFolderId` is missing or does not exist in this environment
             (`FILESERVER_HOME_FOLDER_NOT_FOUND`) or is a file rather than an active folder
             (`FILESERVER_HOME_FOLDER_NOT_FOLDER`).
@@ -490,16 +534,29 @@ paths:
                     errors:
                       - code: FILESERVER_LAST_CREDENTIAL
                         message: An enabled account must have a password
+                weakPassword:
+                  summary: Password shorter than 12 characters
+                  value:
+                    errors:
+                      - code: FILESERVER_WEAK_PASSWORD
+                        message: "Password is too weak.\n\t1. Password must have at least 12 characters."
                 homeFolderMissing:
                   value:
                     errors:
                       - code: FILESERVER_HOME_FOLDER_NOT_FOUND
                         message: The home folder does not exist in this environment
+                homeFolderIsFile:
+                  value:
+                    errors:
+                      - code: FILESERVER_HOME_FOLDER_NOT_FOLDER
+                        message: The home folder target is not an active folder
         '503':
           description: |-
             The home folder is verified against Celigo Storage at create time; when that
             check cannot complete the create is refused with `FILESERVER_STORAGE_UNAVAILABLE`
-            and no account is made. Retry later.
+            and no account is made. Retry later. A `_homeFolderId` that is not a
+            well-formed 24-character hex id is answered this way too, not with 422 —
+            validate the id before sending.
           content:
             application/json:
               schema:
@@ -538,7 +595,7 @@ paths:
                     username: northwind-edi
                     login: northwind-edi@acme-logistics
                     _homeFolderId: 6ab1f25daa3e7ed226ea3f25
-                    homeFolderPath: Partners/Northwind/Inbound
+                    homeFolderPath: /Partners/Northwind/Inbound
                     enabled: true
                     passwordSet: true
                     overCap: false
@@ -561,13 +618,15 @@ paths:
       summary: Update a file server account
       description: |-
         Changes the fields sent and returns the account; fields left out keep their
-        values, and `{}` returns the account unchanged. Renaming keeps `_id` and
-        updates `login`. Moving the home folder is verified against Celigo Storage and
-        ends the account's open sessions, as does disabling it. Re-enabling counts
-        against `limits.maxAccounts` and requires a password to be set. The password
-        cannot be changed here — use `POST /v1/mft/fileserver/accounts/{_id}/password`.
-        Requires a full-access API token, the file server add-on on the license, and a
-        server that has been enabled at least once.
+        values, and `{}` returns the account unchanged without touching `lastModified`.
+        Renaming keeps `_id` and updates `login`. Moving the home folder is verified
+        against Celigo Storage, ends the account's open sessions (as does disabling
+        it), and shifts the delete protection from the old folder to the new one.
+        Re-enabling counts against `limits.maxAccounts` and requires a password to be
+        set. The password cannot be changed here — use
+        `POST /v1/mft/fileserver/accounts/{_id}/password`. Requires a full-access API
+        token, the file server add-on on the license, and a server that has been
+        enabled at least once.
       parameters:
         - $ref: '#/components/parameters/AccountId'
       requestBody:
@@ -585,6 +644,10 @@ paths:
                 summary: Rename
                 value:
                   username: northwind-edi-2
+              moveHomeFolder:
+                summary: Move to another folder
+                value:
+                  _homeFolderId: 6ac5e3371ddaae28c1fea86e
       responses:
         '200':
           description: The account after the change.
@@ -599,7 +662,7 @@ paths:
                     username: northwind-edi
                     login: northwind-edi@acme-logistics
                     _homeFolderId: 6ab1f25daa3e7ed226ea3f25
-                    homeFolderPath: Partners/Northwind/Inbound
+                    homeFolderPath: /Partners/Northwind/Inbound
                     enabled: false
                     passwordSet: true
                     overCap: false
@@ -673,8 +736,17 @@ paths:
                     errors:
                       - code: FILESERVER_LAST_CREDENTIAL
                         message: An enabled account must have a password
+                homeFolderIsFile:
+                  value:
+                    errors:
+                      - code: FILESERVER_HOME_FOLDER_NOT_FOLDER
+                        message: The home folder target is not an active folder
         '503':
-          description: The new home folder could not be verified against Celigo Storage (`FILESERVER_STORAGE_UNAVAILABLE`); nothing changed. Retry later.
+          description: |-
+            The new home folder could not be verified against Celigo Storage
+            (`FILESERVER_STORAGE_UNAVAILABLE`); nothing changed. Retry later. A
+            `_homeFolderId` that is not a well-formed 24-character hex id is answered
+            this way too, not with 422 — validate the id before sending.
           content:
             application/json:
               schema:
@@ -693,9 +765,11 @@ paths:
       summary: Delete a file server account
       description: |-
         Permanently removes the account and ends any session it has open. The home
-        folder and its files are untouched. There is no recycle bin for accounts —
-        recreate one to restore access. Requires a full-access API token, the file
-        server add-on on the license, and a server that has been enabled at least once.
+        folder and its files are untouched, and the folder (with its ancestors) becomes
+        deletable again through `DELETE /v1/storage/items/{_id}`. There is no recycle
+        bin for accounts — recreate one to restore access; a repeated delete answers
+        404. Requires a full-access API token, the file server add-on on the license,
+        and a server that has been enabled at least once.
       parameters:
         - $ref: '#/components/parameters/AccountId'
       responses:
@@ -922,11 +996,61 @@ components:
         storageUsage:
           type: object
           readOnly: true
-          additionalProperties: true
           description: |-
-            Only present on the `PUT` response that enables the server: the environment's
-            Celigo Storage usage as `GET /v1/storage/usage` reports it, checked at enable
-            time because partner uploads land in that storage.
+            Only present on the response to a `PUT` with `enabled: true` — including a
+            repeat on a server that is already enabled: the account's Celigo Storage
+            usage exactly as `GET /v1/storage/usage` reports it, read at enable time
+            because partner uploads land in that storage. Absent on reads.
+          required:
+            - activeUsage
+            - recycleBinUsage
+            - totalUsage
+            - maxAllowedUsage
+            - isOverage
+            - hardLimit
+            - overage
+          properties:
+            activeUsage:
+              type: integer
+              format: int64
+              description: Bytes consumed by active and pending files.
+              examples:
+                - 3387143
+            recycleBinUsage:
+              type: integer
+              format: int64
+              description: Bytes consumed by soft-deleted files still retained in the recycle bin.
+              examples:
+                - 26305326
+            totalUsage:
+              type: integer
+              format: int64
+              description: Sum of `activeUsage` and `recycleBinUsage`; the figure checked against `hardLimit` when a partner uploads.
+              examples:
+                - 29692469
+            maxAllowedUsage:
+              type: integer
+              format: int64
+              description: Storage quota in bytes granted by the account's license.
+              examples:
+                - 214748364800
+            isOverage:
+              type: boolean
+              description: When true, `totalUsage` has passed `maxAllowedUsage` and uploads are consuming the overage buffer up to `hardLimit`.
+              examples:
+                - false
+            hardLimit:
+              type: integer
+              format: int64
+              description: Byte ceiling at which partner uploads are rejected, as `maxAllowedUsage` plus the licensed overage buffer.
+              examples:
+                - 429496729600
+            overage:
+              type: integer
+              format: int64
+              description: Bytes currently consumed beyond `maxAllowedUsage`. Zero when not in overage.
+              examples:
+                - 0
     Error:
       type: object
       description: Standard error response envelope returned by integrator.io APIs.
@@ -1057,8 +1181,10 @@ components:
             Celigo Storage folder that is the root of every session for this account —
             the partner can reach nothing outside it. Must be an active folder in the same
             environment; otherwise the write answers 422 `FILESERVER_HOME_FOLDER_NOT_FOUND`
-            or `FILESERVER_HOME_FOLDER_NOT_FOLDER`. Moving an account to another folder
-            ends its open sessions.
+            or `FILESERVER_HOME_FOLDER_NOT_FOLDER`. While the account exists, this folder
+            and every folder above it refuse `DELETE /v1/storage/items/{_id}` with 403
+            `STORAGE_SFTP_HOME_FOLDER_PROTECTED`; renaming or moving them stays allowed.
+            Moving an account to another folder ends its open sessions.
           examples:
             - 6ab1f25daa3e7ed226ea3f25
         homeFolderPath:
@@ -1067,11 +1193,12 @@ components:
             - 'null'
           readOnly: true
           description: |-
-            Breadcrumb path of `_homeFolderId` from the storage root, for display. Null
-            when the path could not be resolved for this response — the folder id is
-            still authoritative.
+            Absolute path of `_homeFolderId` from the storage root, for display — a
+            leading `/` then the folder names on the way down, following renames and
+            moves of those folders. Null when the path could not be resolved for this
+            response — the folder id is still authoritative.
           examples:
-            - Partners/Northwind/Inbound
+            - /Partners/Northwind/Inbound
         enabled:
           type: boolean
           description: |-
@@ -1155,8 +1282,9 @@ components:
           description: |-
             Partner's password. Needs upper- and lower-case letters, a digit, and a symbol;
             anything weaker is rejected with 422 `FILESERVER_WEAK_PASSWORD` and the message
-            names the rule broken. Never returned by any route — rotate or clear it later
-            through `POST /v1/mft/fileserver/accounts/{_id}/password`.
+            lists every rule broken. A non-string value counts as no password at all (422
+            `FILESERVER_LAST_CREDENTIAL`). Never returned by any route — rotate or clear it
+            later through `POST /v1/mft/fileserver/accounts/{_id}/password`.
           examples:
             - Nw-Inbound-2026!x
         _homeFolderId:
@@ -1166,7 +1294,9 @@ components:
           description: |-
             Celigo Storage folder that becomes the root of the partner's sessions. Must be
             an active folder in this environment — create one with
-            `POST /v1/storage/items` first.
+            `POST /v1/storage/items` first. Once the account exists the folder and its
+            ancestors cannot be deleted from storage until the account is deleted or
+            moved elsewhere.
           examples:
             - 6ab1f25daa3e7ed226ea3f25
       x-celigo-ai-guidance:
@@ -1175,6 +1305,12 @@ components:
           FILESERVER_USERNAME_INVALID (same code as a malformed one), a missing password 422
           FILESERVER_LAST_CREDENTIAL, and a missing _homeFolderId 422
           FILESERVER_HOME_FOLDER_NOT_FOUND — each before anything is created.
+        - |-
+          Send _homeFolderId as the 24-character hex _id returned by POST /v1/storage/items. A
+          malformed value is not a 422: it fails the storage lookup and answers 503
+          FILESERVER_STORAGE_UNAVAILABLE "home-folder validation failed", which looks like an
+          outage. A well-formed id that does not exist answers 422
+          FILESERVER_HOME_FOLDER_NOT_FOUND and a file's id 422 FILESERVER_HOME_FOLDER_NOT_FOLDER.
     FileServerAccountUpdateRequest:
       type: object
       description: |-
@@ -1194,7 +1330,12 @@ components:
           type: string
           format: objectId
           x-celigo-refModel: storageitems
-          description: Move the account to another active folder in this environment. Ends the account's open sessions, which were rooted in the old folder.
+          description: |-
+            Move the account to another active folder in this environment. Ends the
+            account's open sessions, which were rooted in the old folder, and moves the
+            storage delete protection from the old folder to the new one. The same
+            validation and error answers apply as on create, including the 503 for a
+            malformed id.
           examples:
             - 6ab1f25daa3e7ed226ea3f25
         enabled:
@@ -1225,9 +1366,9 @@ components:
             The new password, meeting the same policy as on create (422
             `FILESERVER_WEAK_PASSWORD` otherwise), or `null` to remove the password —
             allowed only while the account is disabled, because an enabled account must
-            keep a credential (422 `FILESERVER_LAST_CREDENTIAL`). Any other type answers
-            422 `FILESERVER_WEAK_PASSWORD` with the message "Password must be a string (or
-            null to clear)."
+            keep a credential (422 `FILESERVER_LAST_CREDENTIAL`). Any other type, or an
+            empty body, answers 422 `FILESERVER_WEAK_PASSWORD` with the message "Password
+            must be a string (or null to clear)."
           examples:
             - Nw-Inbound-2026!y
   responses:

package/dist/filestorage.yml

@@ -1344,10 +1344,14 @@ 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`.
       operationId: deleteStorageItem
       tags:
         - File Storage
@@ -1370,7 +1374,22 @@ paths:
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
-          $ref: '#/components/responses/403-forbidden'
+          description: |-
+            The caller lacks permission for this item, or the folder is (or
+            contains) a File Server account's home folder. Error code:
+            `STORAGE_SFTP_HOME_FOLDER_PROTECTED` for the latter — delete or move
+            the account first.
+          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
         '404':
           $ref: '#/components/responses/404-not-found'
         '422':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.92",
+  "version": "0.2.93",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "ec12d5c1",
+		"iasCommit": "fcb2d9c1",
 		"generatedAt": "2026-10-12"
 	},
 	"roots": {