@celigo/api-specs 0.2.170 → 0.2.171

package/dist/ai-agent.yml

@@ -1232,7 +1232,7 @@ components:
                       x-enumDescriptions:
                         text: Free-form text response from the model.
                         json_schema: Structured JSON output conforming to a defined schema.
-                        blob: Binary data output for non-text content.
+                        blob: Image generation — the run calls the image generation tool and returns the stored image's `blobKey`, not `_text` or `_json`.
                       default: text
                       description: Output format type.
                     schemaMode:
@@ -1454,11 +1454,6 @@ components:
                               an object without a non-empty name fails with a
                               missing-required-field error. String entries are the
                               legacy form and stay valid.
-                      allowedPrompts:
-                        type: array
-                        description: Specific prompts to allow from the MCP server (used for MCP prompt entries; all if omitted).
-                        items:
-                          type: string
                   tool:
                     type: object
                     description: |
@@ -1601,7 +1596,7 @@ components:
                   x-enumDescriptions:
                     text: Free-form text response from the model.
                     json_schema: Structured JSON output conforming to a defined schema.
-                    blob: Binary data output for non-text content.
+                    blob: Image generation — the run returns the stored image's `blobKey`, not `_text` or `_json`.
                   default: text
                 schemaMode:
                   type: string
@@ -1770,11 +1765,6 @@ components:
                                       description: Display description shown for the tool.
                                   required:
                                     - name
-                              allowedPrompts:
-                                type: array
-                                description: Specific prompts to allow from the MCP server (used for MCP prompt entries; all if omitted).
-                                items:
-                                  type: string
                           tool:
                             type: object
                             description: Reference to a Celigo Tool resource, used when type is "tool".
@@ -4398,192 +4388,6 @@ components:
                   - lookupName
               - required:
                   - hardCodedValue
-    ResponseMapping:
-      type: object
-      description: |
-        Merges fields from a step's response back onto the in-flight record so
-        downstream steps can read them. Applies to both lookup steps
-        (`type: "export"`) and import steps (`type: "import"`); without it, the
-        step's response is discarded after the call.
-
-        `fields` and `lists` are plain arrays — exactly the shape GET returns.
-
-        Extract paths do NOT read the raw application response — the platform
-        wraps every response in a canonical per-record envelope first, and
-        extracts evaluate against that envelope:
-
-        - **Lookup steps**: `{"statusCode": 200, "data": [<result records>],
-          "errors": []}` — `data` holds the records the lookup step returns,
-          AFTER the export's own `transform` and output `filter` have run, so
-          extracts must start from it and name transformed fields by their
-          transformed name: `data[0].name` copies a field of the first result,
-          `data` copies the whole result array. A bare result-record field name
-          (e.g. `name`) resolves to nothing and merges nothing, and so does the
-          raw response path a transform consumed. A lookup that groups its
-          results returns each group as an array inside `data`
-          (`"data": [[<row>, <row>]]`): `data[0][0].name` (or `data.0.0.name`)
-          reads the first row of the first group, and `data[0]` copies the group.
-        - **Import steps**: `{"id": "<destination record id>", "statusCode": 200,
-          "ignored": false, "errors": [], "_json": <raw destination response>,
-          ...<response body fields flattened at the root>}` — use `id` for the
-          destination-assigned id and `_json.<path>` (or the flattened
-          `<path>`) for fields inside the destination's response body. The full
-          envelope (including `id`) is present on real runs and in flow-builder
-          previews; flow TEST runs never execute imports, and their envelope is
-          built from the import's saved `mockResponse`, or from the placeholder
-          `{"id": "1234567890", "mockResponse": "replace me"}` (numbered
-          `1234567890-1`, `1234567890-2`, … when a page holds several records)
-          — an `extract: "id"` in a test run merges that mock id, never a
-          destination record id.
-
-        An `extract` may also be a Handlebars expression. It evaluates against
-        the same envelope as a plain path, so every path inside `{{ }}` starts
-        where the plain paths start — `{{data.0.name}}`,
-        `{{#compare data.0.count "==" 1}}yes{{else}}no{{/compare}}`,
-        `{{#if data.length}}found{{/if}}` on a lookup; `{{_json.order.id}}` or
-        `{{id}}` on an import. Index arrays with dots inside Handlebars
-        (`data.0.name` or `data.[0].name`; `data[0].name` renders nothing), and
-        expect a string result (`"1"`, `"false"`). There is no `record` object in
-        this context: `{{record.<anything>}}` renders nothing. Prefer a plain
-        path when the value is simply copied.
-      x-celigo-ai-guidance:
-        - |-
-          Handlebars is allowed in `extract` but only rooted at the envelope —
-          `{{data.0.x}}` on a lookup, `{{_json.x}}` / `{{id}}` on an import. The
-          `record.` root belongs to import-mapping templates; here every
-          `{{record.…}}` form renders nothing, silently, and `{{data[0].x}}`
-          (bracket index inside Handlebars) renders nothing too. Use Handlebars
-          only for a derived value (a flag, a concatenation); copy values with a
-          plain path.
-        - |-
-          A lookup's `data[]` is the step's output after its `transform` and
-          `filter`, so author extracts against the transformed records — never
-          against the raw response the transform consumed, and never against a
-          saved `mockOutput` as stored (it is the raw response; the transform
-          runs on top of it in a test run).
-        - |-
-          Send `fields` and `lists` as bare arrays, exactly as GET returns them.
-          Never wrap either in an object (e.g. `"fields": {"type": [...]}`): the
-          API does not reject that shape — it returns 200 and silently persists
-          `fields: [null]` / `lists: [{"fields": []}]`, erasing the step's
-          response mappings.
-        - |-
-          responseMapping is fully replaced on PUT: omitting it resets the step
-          to empty `{"fields": [], "lists": []}`. Always send the complete
-          intended mapping for every step.
-        - |-
-          To carry several lookup results onto the record, use `extract: "data"`
-          (the whole result array) or a `lists` entry whose extracts use
-          `data[*].x` — never `data[*].x` in `fields[].extract`, which merges
-          nothing: the record simply never gains the field.
-      examples:
-        - fields:
-            - extract: id
-              generate: ContactId
-          lists: []
-        - fields:
-            - extract: data[0].customer.name
-              generate: customerName
-          lists:
-            - generate: matchedOrders
-              fields:
-                - extract: data[*].id
-                  generate: orderId
-                - extract: data[*].total
-                  generate: amount
-      properties:
-        fields:
-          type: array
-          description: |
-            Field mappings that copy individual values from the response
-            envelope onto the in-flight record.
-          items:
-            type: object
-            properties:
-              extract:
-                type: string
-                x-celigo-agent:
-                  - handlebars
-                description: |
-                  Path within the canonical response envelope to copy the value
-                  from, or a Handlebars expression over that same envelope. For
-                  lookup steps, paths start from the envelope's `data` array
-                  (`data[0].x` and `data.0.x` are equivalent; `data` alone
-                  copies every result) — a lookup result field written without
-                  the `data` prefix resolves to nothing. For import steps, use
-                  the envelope fields `id`, `statusCode`, `ignored`, `_json.<path>`
-                  for the raw response body, or the body field itself at the
-                  envelope root (`orderNumber` and `_json.orderNumber` read the
-                  same value). A `[*]` wildcard is not honored here — `data[*].x`
-                  merges nothing; iterate arrays with `lists` instead. Inside
-                  Handlebars, index with dots (`{{data.0.x}}`, never
-                  `{{data[0].x}}`) and never use a `record.` root.
-                examples:
-                  - data[0].customer.name
-                  - data.0.fields.Product Name
-                  - data
-                  - id
-                  - _json.orderNumber
-                  - '{{#if data.length}}found{{else}}missing{{/if}}'
-              generate:
-                type: string
-                description: |
-                  Field path on the in-flight record where the extracted value
-                  is stored, using dot notation for nesting. Downstream steps
-                  read the value at this path.
-                examples:
-                  - customerName
-                  - supplierDetails.supplierName
-                  - netsuite_order_id
-        lists:
-          type: array
-          description: |
-            Array mappings that build a target array on the in-flight record
-            from an array inside the response envelope — one output item per
-            element of the array the item extracts mark with `[*]` (`data[*].x`
-            for lookups, `_json.<arrayPath>[*].x` for imports); an empty source
-            array yields an empty target array. Not needed for one-to-many
-            (fan-out) merge-back, which uses plain field mappings.
-          items:
-            type: object
-            properties:
-              generate:
-                type: string
-                description: |
-                  Array field created on the in-flight record to hold the
-                  mapped items.
-                examples:
-                  - orderItems
-                  - addresses
-                  - contacts
-              fields:
-                type: array
-                description: |
-                  Field mappings applied to each item of the source array to
-                  produce the corresponding target-array item.
-                items:
-                  type: object
-                  properties:
-                    extract:
-                      type: string
-                      description: |
-                        Full envelope path to the source value, with `[*]`
-                        marking the array to iterate — `data[*].productId` for a
-                        lookup, `_json.items[*].sku` for an import. A path without
-                        `[*]` (e.g. `statusCode`) repeats the same envelope value
-                        on every item; an item-relative name (`productId`)
-                        resolves to nothing and produces empty objects.
-                      examples:
-                        - data[*].productId
-                        - data[*].quantity
-                        - _json.items[*].sku
-                    generate:
-                      type: string
-                      description: Target field within each mapped array item.
-                      examples:
-                        - itemId
-                        - qty
-                        - unitPrice
     Filter:
       type: object
       description: |
@@ -5956,8 +5760,14 @@ components:
         mappings:
           allOf:
             - $ref: '#/components/schemas/Mappings'
-        responseMapping:
-          $ref: '#/components/schemas/ResponseMapping'
+          x-celigo-ai-guidance:
+            - |-
+              The mapped record is the agent's input: its `text` is sent as text, `record` as
+              its JSON, and `files` (`[{name, blobKey}]`, blob keys from earlier in the same
+              flow) as attachments. `conversationHistoryId` (at most 200
+              characters) keeps one conversation per agent and id across runs. A record with
+              none of `text`, `record` or `files` is sent whole, as JSON, so with no mappings a
+              record's own top-level `text`, `record` or `files` field is its only input.
         inputContext:
           type: string
           enum:
@@ -5968,7 +5778,9 @@ components:
             envelope: The agent receives records wrapped in an envelope with metadata.
           description: |-
             Selects the data context that `mappings[].extract` evaluates against. With no
-            mappings the agent receives the entire record and `inputContext` is moot. `record`
+            mappings the agent receives the entire record as JSON (or only the record's own
+            top-level `text`, `record` or `files` fields, when it has any) and `inputContext`
+            is moot. `record`
             (the default) extracts against the flat record; `envelope` extracts against the
             runtime envelope, which exposes the record alongside job, settings, and other
             run-time metadata (`$.record.field`, `$.settings.field`, etc.). Same contract as
@@ -6068,6 +5880,13 @@ components:
               _headers:
                 type: object
                 description: Mock response headers.
+              blobKey:
+                type: string
+                description: |-
+                  Mock output of an agent with `blob` output (image generation:
+                  `openai.output.format.type` or `litellm.responseFormat.type` set to `blob`),
+                  which returns the stored image's key here. Unrelated to the import-level `blob`
+                  flag, which agents refuse.
     ResourceResponse:
       type: object
       description: Response

package/dist/audit.yml

@@ -49,6 +49,12 @@ paths:
         exact resource only — to include descendants (e.g. an integration's
         flows and exports), use `GET /v1/{resourceType}/{_id}/audit` instead.
         `_resourceId` requires `resourceType` to also be set.
+
+        Only the account owner and administrators can query the account-wide
+        log: manage, monitor and integration-level users get 403, and an API
+        token with limited scope gets 401 `token_restricted_access`. Those
+        users can still read the history of a resource they can see, through
+        `GET /v1/{resourceType}/{_id}/audit`.
       parameters:
         - name: limit
           in: query
@@ -311,7 +317,9 @@ paths:
         '400':
           $ref: '#/components/responses/400-bad-request'
         '401':
-          $ref: '#/components/responses/401-unauthorized'
+          $ref: '#/components/responses/401-unauthorized-or-scoped-token'
+        '403':
+          $ref: '#/components/responses/403-administrator-only'
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
     post:
@@ -328,7 +336,8 @@ paths:
         identical to `GET /v1/audit`.
 
         Pagination, sorting, and time bounds stay in the query string — sending
-        them in the body fails with 400 `invalid_request_body`.
+        them in the body fails with 400 `invalid_request_body`. The same callers
+        are refused as on `GET /v1/audit`.
       parameters:
         - name: limit
           in: query
@@ -472,7 +481,9 @@ paths:
                       - code: invalid_request_body
                         message: 'The request body should not contain pagination parameter(s): limit. Pagination values (after, before, limit, sort_order, sort_by) must be provided as query parameters. The request body should only contain filter fields.'
         '401':
-          $ref: '#/components/responses/401-unauthorized'
+          $ref: '#/components/responses/401-unauthorized-or-scoped-token'
+        '403':
+          $ref: '#/components/responses/403-administrator-only'
         '422':
           description: |-
             A filter value is invalid, a filter that must be an array was sent as
@@ -502,7 +513,9 @@ paths:
       description: |-
         Generates a signed URL for downloading a CSV export of audit logs across all
         documents. The CSV columns are: Time, Source, User, Resource, Name/ID, Action,
-        Field, Old value, New value, Support.
+        Field, Old value, New value, Support. The same callers are refused as on
+        `GET /v1/audit`: only the account owner and administrators can export the
+        account-wide log.
 
         The signed URL expires after 15 minutes. When `hasMore` is true, pass
         the last CSV row's timestamp as `to` to fetch the next batch.
@@ -686,7 +699,9 @@ paths:
                     signedURL: https://integrator-userdata-delete-30.s3.us-east-1.amazonaws.com/audit/624cb034630.../audit-export.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&...
                     hasMore: false
         '401':
-          $ref: '#/components/responses/401-unauthorized'
+          $ref: '#/components/responses/401-unauthorized-or-scoped-token'
+        '403':
+          $ref: '#/components/responses/403-administrator-only'
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
     post:
@@ -766,7 +781,9 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error'
         '401':
-          $ref: '#/components/responses/401-unauthorized'
+          $ref: '#/components/responses/401-unauthorized-or-scoped-token'
+        '403':
+          $ref: '#/components/responses/403-administrator-only'
         '422':
           $ref: '#/components/responses/422-unprocessable-entity'
   /v1/{resourceType}/{_id}/audit:
@@ -1997,6 +2014,65 @@ components:
                 errors:
                   - code: invalid_request
                     message: The request body failed validation.
+    401-unauthorized-or-scoped-token:
+      description: |-
+        Unauthorized: the request has no valid bearer token (a bare `{message}` body, as on every
+        route), or the token is an API token with limited scope. The account-wide audit query
+        takes only a full-access API token, a personal access token, or a signed-in session; a
+        scoped token is refused with `token_restricted_access` in the standard `{errors: [...]}`
+        envelope.
+      content:
+        application/json:
+          schema:
+            oneOf:
+              - $ref: '#/components/schemas/Error'
+              - type: object
+                description: The auth middleware's bare body for a missing or invalid token.
+                properties:
+                  message:
+                    type: string
+                    description: '`Unauthorized` (no Authorization header) or `Bearer Authentication Failed`.'
+                required:
+                  - message
+          examples:
+            scopedToken:
+              summary: An API token scoped to specific resources
+              value:
+                errors:
+                  - code: token_restricted_access
+                    message: This action is not allowed using API tokens with limited scope.
+            invalidToken:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    403-administrator-only:
+      description: |-
+        The caller is a manage, monitor or integration-level user. The account-wide audit log is
+        for the account owner and administrators; other users read one resource's history with
+        `GET /v1/{resourceType}/{_id}/audit` instead.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            notAdministrator:
+              value:
+                errors:
+                  - code: access_restricted
+                    message: The role which you are associated with doesn't have the required permissions to perform the action.
+    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.
     401-unauthorized:
       description: |-
         Unauthorized. The request lacks a valid bearer token, or the provided token
@@ -2031,19 +2107,6 @@ components:
               summary: Bearer token invalid or revoked
               value:
                 message: Bearer Authentication Failed
-    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.
     404-not-found:
       description: |
         Not found. The requested resource does not exist or is not visible to the caller.

package/dist/fileserver.yml

@@ -9,7 +9,9 @@ info:
       (`GET`/`PUT /v1/mft/fileserver`) and the partner accounts that log in to it
       (`/v1/mft/fileserver/accounts`), each chrooted to a Celigo Storage folder. Requires a
       full-access API token — folder-path-scoped and other restricted tokens answer 403
-      FILESERVER_FULL_ACCESS_TOKEN_REQUIRED on every route.
+      FILESERVER_FULL_ACCESS_TOKEN_REQUIRED on every route, and so does every personal access
+      token, whatever its creator's role. Only the account owner and administrators may manage
+      the server.
 servers:
   - url: https://api.integrator.io
     description: Production (US / default region)
@@ -24,7 +26,7 @@ security:
 tags:
   - name: File Server
     description: |-
-      Each environment can run a Celigo-hosted SFTP file server. Enabling it claims a permanent `identifier` that becomes part of every partner login (`<username>@<identifier>`) and exposes the shared endpoint and host-key fingerprints partners need to connect. Partner accounts are created under the server, each with its own password and a Celigo Storage folder that becomes the account's root, so files a partner uploads appear in that folder and files placed there are what the partner can download. The account's license must include the file server add-on (`fileserver.enabled`), and every call needs a full-access API token.
+      Each environment can run a Celigo-hosted SFTP file server. Enabling it claims a permanent `identifier` that becomes part of every partner login (`<username>@<identifier>`) and exposes the shared endpoint and host-key fingerprints partners need to connect. Partner accounts are created under the server, each with its own password and a Celigo Storage folder that becomes the account's root, so files a partner uploads appear in that folder and files placed there are what the partner can download. The account's license must include the file server add-on (`fileserver.enabled`), and every call needs a full-access API token: scoped tokens and personal access tokens are refused, and so are manage, monitor and integration-level users.
 
       ## File server and account schemas
 
@@ -87,7 +89,11 @@ paths:
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
-          description: The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`).
+          description: |-
+            The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`). A
+            personal access token is refused the same way as a scoped token, and a manage, monitor
+            or integration-level user gets `access_restricted`: only the owner and administrators
+            manage the file server.
           content:
             application/json:
               schema:
@@ -98,6 +104,12 @@ paths:
                     errors:
                       - code: FILESERVER_FULL_ACCESS_TOKEN_REQUIRED
                         message: The file server management APIs require an API token with full access
+                notAdministrator:
+                  summary: A manage, monitor or integration-level user
+                  value:
+                    errors:
+                      - code: access_restricted
+                        message: The role which you are associated with doesn't have the required permissions to perform the action.
         '404':
           description: The environment is entitled but its server has never been enabled (`FILESERVER_NOT_FOUND`).
           content:
@@ -220,7 +232,7 @@ paths:
           description: |-
             The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`),
             the account's license lacks the file server add-on or the environment is a
-            sandbox (`FILESERVER_NOT_ENTITLED`).
+            sandbox (`FILESERVER_NOT_ENTITLED`). A personal access token is refused the same way as a scoped token, and a manage, monitor or integration-level user gets `access_restricted`: only the owner and administrators manage the file server.
           content:
             application/json:
               schema:
@@ -231,6 +243,12 @@ paths:
                     errors:
                       - code: FILESERVER_NOT_ENTITLED
                         message: The file server add-on is not enabled for this account
+                notAdministrator:
+                  summary: A manage, monitor or integration-level user
+                  value:
+                    errors:
+                      - code: access_restricted
+                        message: The role which you are associated with doesn't have the required permissions to perform the action.
         '404':
           description: A disable was sent for an environment whose server was never enabled (`FILESERVER_NOT_FOUND`).
           content:
@@ -396,7 +414,11 @@ paths:
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
-          description: The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`), or the environment is a sandbox (`FILESERVER_NOT_ENTITLED`).
+          description: |-
+            The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`), or
+            the environment is a sandbox (`FILESERVER_NOT_ENTITLED`). A personal access token is
+            refused the same way as a scoped token, and a manage, monitor or integration-level user
+            gets `access_restricted`: only the owner and administrators manage the file server.
           content:
             application/json:
               schema:
@@ -407,6 +429,12 @@ paths:
                     errors:
                       - code: FILESERVER_FULL_ACCESS_TOKEN_REQUIRED
                         message: The file server management APIs require an API token with full access
+                notAdministrator:
+                  summary: A manage, monitor or integration-level user
+                  value:
+                    errors:
+                      - code: access_restricted
+                        message: The role which you are associated with doesn't have the required permissions to perform the action.
         '422':
           description: The environment's server has never been enabled (`FILESERVER_NOT_ENABLED`); a disabled server is still manageable.
           content:
@@ -487,7 +515,7 @@ paths:
             The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`);
             the license lacks the add-on or the environment is a sandbox
             (`FILESERVER_NOT_ENTITLED`); or the environment already holds
-            `limits.maxAccounts` enabled accounts (`FILESERVER_MAX_ACCOUNTS_EXCEEDED`).
+            `limits.maxAccounts` enabled accounts (`FILESERVER_MAX_ACCOUNTS_EXCEEDED`). A personal access token is refused the same way as a scoped token, and a manage, monitor or integration-level user gets `access_restricted`: only the owner and administrators manage the file server.
           content:
             application/json:
               schema:
@@ -498,6 +526,12 @@ paths:
                     errors:
                       - code: FILESERVER_MAX_ACCOUNTS_EXCEEDED
                         message: The maximum number of enabled accounts for this environment has been reached
+                notAdministrator:
+                  summary: A manage, monitor or integration-level user
+                  value:
+                    errors:
+                      - code: access_restricted
+                        message: The role which you are associated with doesn't have the required permissions to perform the action.
         '409':
           description: Another account in this environment already has that username, enabled or not (`FILESERVER_USERNAME_TAKEN`).
           content:
@@ -688,7 +722,7 @@ paths:
             The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`);
             the license lacks the add-on or the environment is a sandbox
             (`FILESERVER_NOT_ENTITLED`); or re-enabling would exceed `limits.maxAccounts`
-            (`FILESERVER_MAX_ACCOUNTS_EXCEEDED`).
+            (`FILESERVER_MAX_ACCOUNTS_EXCEEDED`). A personal access token is refused the same way as a scoped token, and a manage, monitor or integration-level user gets `access_restricted`: only the owner and administrators manage the file server.
           content:
             application/json:
               schema:
@@ -699,6 +733,12 @@ paths:
                     errors:
                       - code: FILESERVER_MAX_ACCOUNTS_EXCEEDED
                         message: The maximum number of enabled accounts for this environment has been reached
+                notAdministrator:
+                  summary: A manage, monitor or integration-level user
+                  value:
+                    errors:
+                      - code: access_restricted
+                        message: The role which you are associated with doesn't have the required permissions to perform the action.
         '404':
           $ref: '#/components/responses/404-account-not-found'
         '409':
@@ -1407,7 +1447,12 @@ components:
               value:
                 message: Bearer Authentication Failed
     403-full-access-required:
-      description: The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`), or the license lacks the add-on / the environment is a sandbox (`FILESERVER_NOT_ENTITLED`).
+      description: |-
+        The token is not a full-access API token (`FILESERVER_FULL_ACCESS_TOKEN_REQUIRED`) --
+        a scoped API token, or any personal access token, which never counts as full access --
+        or the license lacks the add-on / the environment is a sandbox (`FILESERVER_NOT_ENTITLED`).
+        A manage, monitor or integration-level user is refused with `access_restricted`: only the
+        account owner and administrators manage the file server.
       content:
         application/json:
           schema:
@@ -1418,6 +1463,12 @@ components:
                 errors:
                   - code: FILESERVER_FULL_ACCESS_TOKEN_REQUIRED
                     message: The file server management APIs require an API token with full access
+            notAdministrator:
+              summary: A manage, monitor or integration-level user
+              value:
+                errors:
+                  - code: access_restricted
+                    message: The role which you are associated with doesn't have the required permissions to perform the action.
     404-account-not-found:
       description: No account with this id in the caller's environment, or the id is not a valid identifier (`FILESERVER_ACCOUNT_NOT_FOUND`).
       content: