@celigo/api-specs 0.2.25 → 0.2.27

package/dist/mcp-server.yml

@@ -18,6 +18,7 @@ info:
       - Supports tool overrides for customizing connections, exports, imports, and routing per-server
       - Exposes prompts via `prompts/list` and `prompts/get` with Handlebars-style argument substitution
       - Carries **permission sets** ("Capability Sets" in the UI) — named bundles of its tools and APIs granted to end users via `pset:<_id>` capability strings on end-user, group, and role resource grants
+      - Carries optional **traffic limits** (`policies[]`) — a server-level rate limit, a per-user rate limit for OAuth end users, and a usage quota — enforced before a tool runs; a rejected call gets HTTP 429 with `Retry-After`
 servers:
   - url: https://api.integrator.io
     description: Production (US / default region)
@@ -43,7 +44,10 @@ tags:
       and routing. Permission sets ("Capability Sets" in the UI) bundle a
       server's tools and APIs into named grants for end users, and the
       server-scoped access endpoints bulk-assign capabilities to end users
-      and groups and report compiled effective access.
+      and groups and report compiled effective access. Optional traffic
+      limits (`policies`) — a server-level rate limit, a per-user rate
+      limit, and a usage quota — reject calls over the limit with HTTP 429
+      and `Retry-After` before any tool runs.
 
       ## MCP server schema
 
@@ -269,10 +273,11 @@ paths:
       summary: Update an MCP server
       description: |-
         Full replacement of an MCP server's configuration. Omitted arrays
-        (`tools`, `apis`, `prompts`, `resources`, `permissionSets`) are cleared,
-        so include the complete arrays — clearing `permissionSets` this way also
-        rewrites the `pset:` grants that referenced the erased sets. `relativeURI`
-        can be changed but must remain unique per account.
+        (`tools`, `apis`, `prompts`, `resources`, `permissionSets`, `policies`)
+        are cleared, so include the complete arrays — clearing `permissionSets`
+        this way also rewrites the `pset:` grants that referenced the erased sets,
+        and clearing `policies` removes every traffic limit. `relativeURI` can be
+        changed but must remain unique per account.
       operationId: updateMcpServer
       tags:
         - MCP Servers
@@ -386,8 +391,14 @@ paths:
       summary: Patch an MCP server
       description: |-
         Partially updates an MCP server using a JSON Patch document (RFC 6902).
-        Only `/name` and `/disabled` are whitelisted paths — all other paths
-        are rejected with `not a whitelisted property`.
+        Only `/name`, `/disabled`, and `/policies` are whitelisted paths — all
+        other paths are rejected with `not a whitelisted property`. Under
+        `/policies`, `add`, `replace`, and `remove` work on the whole array,
+        `add` works at `/policies/-` or an index, and `replace` works at an index
+        or a sub-path such as `/policies/0/config/limit`; `remove` at an array
+        index is rejected with 422 `Remove at array index is not supported`. The
+        resulting array is validated as a whole, and an invalid policy rejects
+        the entire patch.
       operationId: patchMcpServer
       tags:
         - MCP Servers
@@ -421,6 +432,40 @@ paths:
                   - op: replace
                     path: /name
                     value: Updated Server Name
+              set_traffic_limits:
+                summary: Set a server rate limit, a per-user rate limit, and a monthly quota
+                value:
+                  - op: replace
+                    path: /policies
+                    value:
+                      - type: rate-limit
+                        name: Server-level rate limit
+                        enabled: true
+                        config:
+                          limit: 600
+                          periodTime: 1
+                          periodTimeUnit: MINUTE
+                      - type: rate-limit
+                        name: Per-user rate limit
+                        enabled: true
+                        config:
+                          limit: 60
+                          periodTime: 1
+                          periodTimeUnit: MINUTE
+                          keyResolver: consumer
+                      - type: quota
+                        name: Monthly usage quota
+                        enabled: true
+                        config:
+                          limit: 500000
+                          periodTime: 1
+                          periodTimeUnit: MONTH
+              remove_traffic_limits:
+                summary: Remove every traffic limit (unlimited)
+                value:
+                  - op: replace
+                    path: /policies
+                    value: []
       responses:
         '204':
           description: Patch applied.
@@ -1724,6 +1769,217 @@ components:
       required:
         - name
         - accessLevel
+    Policy:
+      type: object
+      description: |-
+        One traffic limit the server enforces before a tool runs — shown under
+        **Access > Governance** in the UI. A `rate-limit` caps calls per MINUTE,
+        HOUR, or DAY with a continuously refilling allowance, either for the whole
+        server (`keyResolver` `endpoint`) or separately for each OAuth end user
+        (`keyResolver` `consumer`); a `quota` caps cumulative calls over a UTC
+        calendar DAY, WEEK, or MONTH across every consumer. A call must pass every
+        enabled policy. A rejected call is not executed and receives HTTP 429 with
+        a `Retry-After` header (seconds until the allowance refills or the quota
+        period resets), an `X-RateLimit-Limit` header, and a JSON-RPC error
+        (code -32004) whose message names the policy: `Rate limit exceeded: <name>`
+        or `Usage quota exceeded: <name>`.
+      x-celigo-ai-guidance:
+        - |-
+          Configure one policy per kind — one server-level rate limit, one per-user
+          rate limit (`keyResolver` `consumer`), one quota. The API does not reject a
+          second policy of the same kind; both are then enforced against the same
+          traffic, which makes the effective limit hard to reason about.
+        - |-
+          A `tools/call` counts against every enabled policy, even when the named tool
+          does not exist; `initialize`, `tools/list`, `prompts/list`, and `resources/list`
+          are never counted or rejected (all live-verified). Whether `prompts/get` and
+          `resources/read` count has not been verified — do not assert either way.
+        - |-
+          Bearer API-token traffic is evaluated by `endpoint`-keyed rate limits and by
+          quotas only; a `consumer`-keyed rate limit applies to OAuth end users, each
+          with an independent allowance, and leaves API-token traffic untouched.
+        - |-
+          A rate limit keeps its allowance state when its `limit` is changed, so raising
+          a limit right after it tripped admits nothing until tokens refill at the new
+          rate. A quota counts every call the server accepted in the current UTC period,
+          including calls made before the quota was configured — a quota below the
+          period's current count rejects every call until the period resets.
+      required:
+        - type
+        - name
+        - config
+      properties:
+        type:
+          type: string
+          enum:
+            - rate-limit
+            - quota
+          x-enumDescriptions:
+            rate-limit: Caps calls per MINUTE, HOUR, or DAY with an allowance that refills continuously; server-wide, or per end user with keyResolver consumer
+            quota: Caps cumulative calls over a UTC calendar DAY, WEEK, or MONTH for every consumer combined
+          description: |-
+            Kind of limit. Use rate-limit to protect downstream systems from bursts
+            and, with `keyResolver` `consumer`, to keep one end user from consuming
+            the whole server; use quota to cap total consumption for cost control.
+          examples:
+            - rate-limit
+        name:
+          type: string
+          maxLength: 100
+          description: |-
+            Label for the limit, echoed verbatim in the 429 error message that
+            rejected clients receive — name it the way consumers should read it.
+          examples:
+            - Server-level rate limit
+            - Per-user rate limit
+            - Monthly usage quota
+        enabled:
+          type: boolean
+          default: true
+          description: |-
+            When true, the policy is enforced. Set to false to keep the
+            configuration in place without enforcing it.
+          examples:
+            - true
+        config:
+          type: object
+          additionalProperties: false
+          description: |-
+            Limit value and period. The maximum `limit` depends on the unit and
+            equals the platform ceiling of 300 calls per second over one period.
+          required:
+            - limit
+            - periodTime
+            - periodTimeUnit
+          properties:
+            limit:
+              type: integer
+              minimum: 1
+              description: |-
+                Maximum number of counted calls in one period. Ceilings per unit:
+                18000 per MINUTE, 1080000 per HOUR, 25920000 per DAY, 181440000 per
+                WEEK, 777600000 per MONTH — higher values are rejected with 422
+                `policy_config_invalid`.
+              examples:
+                - 600
+            periodTime:
+              type: integer
+              const: 1
+              default: 1
+              description: |-
+                Number of `periodTimeUnit` units in one period. Only a single unit
+                is supported; any other value is rejected with 422.
+              examples:
+                - 1
+            periodTimeUnit:
+              type: string
+              enum:
+                - MINUTE
+                - HOUR
+                - DAY
+                - WEEK
+                - MONTH
+              x-enumDescriptions:
+                MINUTE: One-minute period; rate limits only
+                HOUR: One-hour period; rate limits only
+                DAY: One calendar day (UTC) for quotas, or a one-day refilling allowance for rate limits
+                WEEK: One calendar week (UTC); quotas only
+                MONTH: One calendar month (UTC); quotas only
+              description: |-
+                Length of one period. Rate limits take MINUTE, HOUR, or DAY; quotas
+                take DAY, WEEK, or MONTH — any other pairing, or a lowercase value,
+                is rejected with 422 `policy_config_invalid`.
+              examples:
+                - MINUTE
+            keyResolver:
+              type: string
+              enum:
+                - endpoint
+                - consumer
+              default: endpoint
+              x-enumDescriptions:
+                endpoint: One shared allowance for the whole server across every consumer and authentication method
+                consumer: A separate allowance for each OAuth end user; bearer API-token traffic is not evaluated by this policy
+              description: |-
+                Whose allowance the limit tracks. Omit it (or send endpoint) for a
+                server-level limit and send consumer for a per-user rate limit;
+                quotas accept endpoint only.
+              examples:
+                - endpoint
+          if:
+            properties:
+              periodTimeUnit:
+                const: MINUTE
+            required:
+              - periodTimeUnit
+          then:
+            properties:
+              limit:
+                maximum: 18000
+          else:
+            if:
+              properties:
+                periodTimeUnit:
+                  const: HOUR
+              required:
+                - periodTimeUnit
+            then:
+              properties:
+                limit:
+                  maximum: 1080000
+            else:
+              if:
+                properties:
+                  periodTimeUnit:
+                    const: DAY
+                required:
+                  - periodTimeUnit
+              then:
+                properties:
+                  limit:
+                    maximum: 25920000
+              else:
+                if:
+                  properties:
+                    periodTimeUnit:
+                      const: WEEK
+                  required:
+                    - periodTimeUnit
+                then:
+                  properties:
+                    limit:
+                      maximum: 181440000
+                else:
+                  properties:
+                    limit:
+                      maximum: 777600000
+      if:
+        properties:
+          type:
+            const: rate-limit
+        required:
+          - type
+      then:
+        properties:
+          config:
+            properties:
+              periodTimeUnit:
+                enum:
+                  - MINUTE
+                  - HOUR
+                  - DAY
+      else:
+        properties:
+          config:
+            properties:
+              periodTimeUnit:
+                enum:
+                  - DAY
+                  - WEEK
+                  - MONTH
+              keyResolver:
+                enum:
+                  - endpoint
     OAuthConfig:
       type: object
       description: |-
@@ -1965,12 +2221,28 @@ components:
             `resources`, the field is not normalized to an empty array).
           x-celigo-ai-guidance:
             - |-
-              Not editable via PATCH (the whitelist covers only `/name` and
-              `/disabled`). To change permission sets safely, GET the server,
+              Not editable via PATCH (the whitelist covers only `/name`,
+              `/disabled`, and `/policies`). To change permission sets safely, GET the server,
               modify `permissionSets`, and PUT the complete document back with
               every set's `_id` intact.
           items:
             $ref: '#/components/schemas/PermissionSet'
+        policies:
+          type: array
+          description: |-
+            Traffic limits enforced on this server before a tool runs — a
+            server-level rate limit, a per-user rate limit, and a usage quota, each
+            optional and independent. An empty array (the default) means unlimited.
+            Always returned; servers saved before traffic limits existed return an
+            empty array. Omitting the field on PUT clears every limit — send the
+            complete array back, or edit it with PATCH.
+          x-celigo-ai-guidance:
+            - |-
+              Leave `policies` empty unless the user asks for a limit — that is today's
+              default behavior. To change limits without touching the rest of the
+              document, PATCH `replace /policies` with the complete array.
+          items:
+            $ref: '#/components/schemas/Policy'
         oauth:
           $ref: '#/components/schemas/OAuthConfig'
     ResourceResponse:
@@ -2065,9 +2337,9 @@ components:
       type: object
       description: |-
         Request body for creating or updating an MCP server. On PUT, include
-        the full `tools`, `apis`, and `resources` arrays because omitted arrays
-        are cleared. Use PATCH to update individual fields without affecting
-        these arrays.
+        the full `tools`, `apis`, `prompts`, `resources`, `permissionSets`, and
+        `policies` arrays because omitted arrays are cleared. Use PATCH to update individual
+        fields without affecting these arrays.
       x-celigo-ai-guidance:
         - |-
           MCP servers expose Celigo tools, builder-mode APIs,

package/dist/tradingpartnerconnector.yml

@@ -1396,12 +1396,22 @@ components:
         `preConfiguredFields` must include a `type` path (e.g. `ftp` or
         `as2`) and export/import must include `file.type` set to
         `filedefinition` -- these are validated when `published` is `true`.
+
+        `type`, `region`, and `model` must match the deployment's configured
+        values exactly, including case. A value outside the list is not
+        rejected with a validation error: the request never completes (no
+        response is returned) and nothing is created or changed.
       x-celigo-ai-guidance:
         - |-
           Trading partner connectors define reusable templates for onboarding EDI trading partners.
           They specify which fields are pre-configured and which fields the user must
           provide for connections,
           exports, imports, and EDI profiles.
+        - |-
+          Send `type`, `region`, and `model` exactly as configured (`AS2`, not `as2`;
+          `North America`; `Dropship`). An out-of-list value gets no response at all — the
+          create or update never completes and nothing is saved — so a request that hangs
+          on this endpoint means a categorization value is wrong, not that the platform is slow.
         - |-
           When `published` is true, the connector's `supportedBy` sections are validated
           to ensure all required fields are present. For example:

package/dist/user.yml

@@ -125,7 +125,10 @@ paths:
       operationId: getUser
       tags:
         - Users
-      description: Retrieve a single user's access record by its id.
+      description: |-
+        Retrieve a single user's access record by its id. Returns workspace
+        records only — an end-user access-record id is not found here; read
+        those from `GET /v1/endusers`.
       parameters:
         - name: _id
           in: path
@@ -173,10 +176,17 @@ paths:
       tags:
         - Users
       description: |-
-        Update a user's access level, integration permissions, or account
-        settings. The user's email cannot be changed after invite. To
-        disable a user without deleting, use `PUT /v1/ashares/{_id}/disable`
-        instead.
+        Replaces a workspace user's access settings. The body must grant access
+        through `accessLevel` or a non-empty `integrationAccessLevel`, and
+        `integrationAccessLevel`, `accountSSORequired`, and `accountMFARequired`
+        are cleared when omitted — send every value to keep. `disabled` is not
+        applied here; toggle it with `PUT /v1/ashares/{_userId}/disable`.
+        Read-only fields echoed from the GET response are ignored, except
+        `userType`, which is rejected. The user's email cannot be changed after
+        invite. Callable from the production environment only.
+
+        End-user access records share this route with a different body — see
+        the End Users API.
       parameters:
         - name: _id
           in: path
@@ -193,30 +203,81 @@ paths:
               $ref: '#/components/schemas/Request'
             examples:
               changeAccessLevel:
-                summary: Change to administrator
+                summary: Change to administrator (resend the SSO/MFA settings — omitted ones are cleared)
                 value:
                   accessLevel: administrator
+                  integrationAccessLevel: []
+                  accountSSORequired: false
+                  accountMFARequired: true
               integrationOnly:
-                summary: Integration-only access
+                summary: Integration-only access (no accessLevel; resend the SSO/MFA settings)
                 value:
                   integrationAccessLevel:
                     - _integrationId: 68f52162f00a35a1b26eaafb
                       accessLevel: manage
                     - _integrationId: 6842261335b64c0bcb308e4f
                       accessLevel: monitor
-              disableUser:
-                summary: Re-enable a disabled user
+                  accountSSORequired: false
+                  accountMFARequired: true
+              keepSettings:
+                summary: Change access level, keeping every other setting
                 value:
-                  disabled: false
+                  accessLevel: monitor
+                  integrationAccessLevel: []
+                  accountSSORequired: false
+                  accountMFARequired: true
+                  allowToEditRetryData: true
       responses:
         '204':
           description: User updated.
         '400':
-          $ref: '#/components/responses/400-bad-request'
+          description: The body grants no access, or echoes the read-only `userType`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                noAccessGranted:
+                  summary: Neither accessLevel nor integrationAccessLevel sent
+                  value:
+                    errors:
+                      - code: invalid_request
+                        message: To update the account access you need to either provide account level access or integration level access.
+                userTypeEchoed:
+                  summary: Read-only userType sent back
+                  value:
+                    errors:
+                      - code: validation_failed
+                        message: userType is immutable after creation.
         '401':
           $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: The call was made from a sandbox environment.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                sandboxEnvironment:
+                  value:
+                    errors:
+                      - code: access_restricted
+                        message: This request can only be made through the production environment.
         '404':
           $ref: '#/components/responses/404-not-found'
+        '422':
+          description: '`integrationAccessLevel` is empty and no `accessLevel` was sent.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                emptyIntegrationAccess:
+                  value:
+                    errors:
+                      - code: missing_required_field
+                        field: accessLevel
+                        message: You need to provide user with either an account level access or integration level access.
     delete:
       x-internal: false
       summary: Delete a user
@@ -251,8 +312,12 @@ paths:
       summary: Toggle a user's account access (disable or re-enable)
       description: |-
         Toggles the `disabled` flag on a user's access record. Call again to
-        re-enable — there is no separate `/enable` path. Only works on users
-        with `accepted: true`.
+        re-enable — there is no separate `/enable` path, and this is the only
+        way to change `disabled` (the update operation does not apply it). A
+        pending invitation cannot be toggled until the invited user accepts or
+        declines it.
+
+        End-user access records share this route — see the End Users API.
       parameters:
         - name: _userId
           in: path
@@ -278,7 +343,17 @@ paths:
         '204':
           description: User access toggled.
         '400':
-          $ref: '#/components/responses/400-bad-request'
+          description: The invitation is still pending.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                pendingInvitation:
+                  value:
+                    errors:
+                      - code: invalid_request
+                        message: You can't disable this invitation without it being accepted or dismissed by the invited user.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
@@ -435,9 +510,6 @@ components:
       type: object
       description: Writable fields shared by the request and response schemas.
       properties:
-        disabled:
-          type: boolean
-          description: Set to False to enable a disabled user, or True to maintain disabled
         accessLevel:
           type: string
           description: |-
@@ -452,8 +524,14 @@ components:
               `integrationAccessLevel` undefined/empty
 
             If per-integration level permissions are needed, omit `accessLevel` and instead populate `integrationAccessLevel`.
+
+            On update (`PUT /v1/ashares/{_id}`) the body replaces the access settings: `integrationAccessLevel`,
+            `accountSSORequired`, and `accountMFARequired` are cleared when omitted, so resend every value to keep.
           x-celigo-ai-guidance:
             - Choose the `accessLevel` value based on what the user should be able to do across the account.
+            - |-
+              On PUT, "omit" means "clear" for integrationAccessLevel, accountSSORequired, and
+              accountMFARequired — GET the record first and resend those three with the new accessLevel.
           enum:
             - monitor
             - manage
@@ -472,6 +550,8 @@ components:
             - If `accessLevel` is omitted, this creates **integration-only** access.
             - If `accessLevel` is `monitor`, this grants **elevated access** (typically `manage`) for specific integrations.
             - If `accessLevel` is `manage` or `administrator`, do not set `integrationAccessLevel`.
+
+            Cleared when omitted on update — send `[]` explicitly only when you mean no per-integration grants.
           items:
             type: object
             properties:
@@ -493,12 +573,16 @@ components:
                   manage: Full access to edit the integration and its resources.
         accountSSORequired:
           type: boolean
-          description: When true, SSO is required for this user in this account.
+          description: |-
+            When true, SSO is required for this user in this account. Cleared when
+            omitted on update — resend it with every `PUT /v1/ashares/{_id}`.
           x-celigo-ai-guidance:
             - Whether the invited user must use SSO to access this account.
         accountMFARequired:
           type: boolean
-          description: When true, MFA is required for this user in this account.
+          description: |-
+            When true, MFA is required for this user in this account. Cleared when
+            omitted on update — resend it with every `PUT /v1/ashares/{_id}`.
           x-celigo-ai-guidance:
             - Whether the invited user must use MFA to access this account.
         allowAccessToAPIM:
@@ -601,6 +685,13 @@ components:
               type: boolean
               readOnly: true
               description: When true, the user has accepted the invitation to join the account.
+            disabled:
+              type: boolean
+              readOnly: true
+              description: |-
+                When true, the user's access to the account is suspended. Changed
+                only by `PUT /v1/ashares/{_userId}/disable` — a value sent on the
+                update operation is accepted but not applied.
             userType:
               type: string
               readOnly: true
@@ -608,8 +699,10 @@ components:
                 - workspace
               description: |-
                 Discriminates workspace users from end users on the underlying
-                access-record model. This endpoint only returns `workspace`
-                records — end users are managed through the End Users API.
+                access-record model. Reads on this API return only `workspace`
+                records — end users are managed through the End Users API, which
+                shares the update and disable routes. Sending it back on update
+                is rejected.
               x-enumDescriptions:
                 workspace: A workspace (team member) access record.
             lastSignIn:

package/package.json

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