@celigo/api-specs 0.2.209 → 0.2.211

package/dist/export.yml

@@ -1468,6 +1468,9 @@ components:
             - exported_to_netsuite
     Webhook:
       type: object
+      required:
+        - verify
+      x-celigo-ui-override: 'verify is required by the webhook listener form for every provider (exports/webhook.js: verify required:true; on a connector-backed listener the form pre-fills it from the connector definition before saving). The API enforces it only when provider is custom or absent — 422 missing_required_field on webhook.verify, "verify is required for export type webhook, provider = custom". For the named providers probed (slack, shopify, github) it stores a listener posted with key and no verify (201 each; the GET carries provider, key and formType simple) and requires a credential instead: without key (and no token) each answers 422 missing_required_field on webhook.key — "key is required for slack verification" / "key is required for shopify verification" / "key is required for github verification"; a slack listener posted with token and no key saved. Other named providers are unprobed. The requirement is kept so an authored document matches a form-saved one.'
       description: Configuration for webhook listeners that receive data through incoming HTTP requests. Required when the export's `type` is `webhook`; omit for other export types. Senders POST to the export's listener URL, `https://api.integrator.io/v1/exports/{_id}/data` (or the same path on the account's regional API host); the platform validates each request using the configured `verify` method, passes the payload to subsequent flow steps, and returns a configurable HTTP response to the caller. A request is answered 204 by default when accepted, 401 when it fails verification, and 403 `unable_to_run_flows` while every flow the export feeds is disabled; a refused request is not queued, so the sender must resend it.
       x-celigo-ai-guidance:
         - Configuration object for real-time event listeners that receive data via incoming HTTP requests.
@@ -1542,7 +1545,7 @@ components:
       properties:
         provider:
           type: string
-          description: Source application sending the webhook, used to pre-configure security settings and payload parsing for that platform. Use `custom` (the default when omitted) for unlisted providers or when you need full manual control over the security configuration. Provider-specific choices may require credentials (tokens, keys) mandated by that platform.
+          description: 'Source application sending the webhook. A named provider labels the listener and opens it in the Simple form view, where the form pre-fills that platform''s verification settings and payload parsing before saving; the API itself stores the document as sent and fills nothing in. Use `custom` (the default when omitted) for unlisted providers or when you need full manual control over the security configuration. A named provider requires a credential: `key` for the providers probed (shopify, github, slack — and slack also saves with `token` alone); the HMAC settings a provider''s form pre-fills are the form''s, not an API requirement (see the guidance below).'
           x-celigo-ai-guidance:
             - |-
               Specifies the source application sending webhook data,
@@ -1553,10 +1556,18 @@ components:
               This field determines how the webhook handles incoming requests:
 
               - OPTIONAL: Defaults to "custom" if not specified
-              - When a specific provider is selected, the system:
-                1. Pre-configures appropriate security settings for that platform
-                2. Applies platform-specific payload parsing rules
-                3. May enable additional features only relevant to that provider
+              - A named provider labels the listener, picks its form view (`formType`
+                defaults to `simple`) and makes a credential required — probed for
+                `slack`, `shopify` and `github`: without `key` (and no `token`) each
+                fails with 422 missing_required_field on `webhook.key`, "key is required
+                for slack verification" / "key is required for shopify verification" /
+                "key is required for github verification"; a `slack` listener posted
+                with `token` and no `key` saved. It does NOT make the API fill in
+                `verify` and its companions — a document sent to the API stores exactly
+                what it carries, and the listener form fills them from the connector
+                definition before saving. Send them when the stored document should
+                match a form-saved one (Slack: `verify: hmac`, `algorithm: sha256`,
+                `encoding: base64`, `header: X-Slack-Signature`).
             - |-
               ## IMPLEMENTATION GUIDANCE
 
@@ -1566,9 +1577,10 @@ components:
               ```
               "provider": "shopify"
               ```
-              - Automatically configures proper HMAC verification settings
-              - Optimizes payload parsing for Shopify's webhook format
-              - May enable additional Shopify-specific features
+              - Labels the listener as Shopify's and opens it in the Simple form view
+              - Requires `key` (422 "key is required for shopify verification"); saves
+                without `verify` and its companions, which the form would have filled in —
+                send them for a document that matches a form-saved one
 
               ### Custom configuration
 
@@ -1584,7 +1596,7 @@ components:
 
               Choose a specific provider when:
               - The source system is explicitly listed in the enum values
-              - You want to leverage pre-configured settings
+              - You want the form's pre-filled verification settings for that platform
               - The integration must follow platform-specific practices
 
               Choose "custom" when:
@@ -1631,7 +1643,7 @@ components:
             shopify: Shopify store event webhooks with HMAC-SHA256 verification.
             travis: Travis CI build event webhooks (travis-ci.com).
             travis-org: Travis CI build event webhooks (travis-ci.org).
-            slack: Slack workspace event webhooks with token verification.
+            slack: Slack workspace event webhooks. The Simple form pre-fills HMAC-SHA256 over the `X-Slack-Signature` header with the app's signing secret as `key`; the API itself accepts either `key` or `token` as the credential (probed 2026-10-29) and pre-fills nothing.
             dropbox: Dropbox file change notification webhooks.
             onfleet: Onfleet delivery management event webhooks.
             helpscout: Help Scout customer support event webhooks.
@@ -1673,13 +1685,19 @@ components:
             Which webhook export form the UI uses to edit this listener. A value sent on create or
             update wins (case-insensitive — `Simple` is stored as `simple`); a PUT that omits it
             keeps the stored value, and a new export without one gets the default for its
-            `provider`. Every webhook export GET carries it.
-          examples:
-            - webhook
+            `provider`. Every webhook export GET carries it. The view changes nothing at run time:
+            the listener URL, the verification and the flows are the same in both.
+          x-celigo-ai-guidance:
+            - |-
+              Omit it on create — the API stamps the provider's default (`simple` for a named
+              provider, `webhook` for `custom`), with or without `_httpConnectorId`, and keeps a
+              value the user set by hand. The legacy UI values `http` / `assistant` fail with 422
+              `enum`, and the field is not PATCH-whitelisted (422 "not a whitelisted property"):
+              change it through a full save.
         verify:
           type: string
           x-celigo-ui-override: Required by the webhook export form (verify is required:true). Encoded to mirror the form so builders produce connectable configurations.
-          description: 'Verification method applied to every incoming request before processing; required for all webhook exports. Each method needs companion fields: `hmac` requires `key`, `algorithm`, `encoding`, and `header` (except on connector-backed webhooks, where the connector definition supplies them); `token` requires `token`, with `tokenLocation` defaulting to `body` and selecting which location-specific field applies; `basic` requires `username` and `password`; `secret_url` requires `token`. Prefer `hmac` when the source system supports it — it is the most secure option; `secret_url` relies only on URL obscurity and suits non-sensitive data or testing.'
+          description: 'Verification method applied to every incoming request before processing; required for all webhook exports. Each method needs companion fields: `hmac` requires `key`, `algorithm`, `encoding`, and `header` (on connector-backed webhooks the form does not require them — it fills them from the connector definition before saving; the API itself copies nothing); `token` requires `token`, with `tokenLocation` defaulting to `body` and selecting which location-specific field applies; `basic` requires `username` and `password`; `secret_url` requires `token`. Prefer `hmac` when the source system supports it — it is the most secure option; `secret_url` relies only on URL obscurity and suits non-sensitive data or testing.'
           x-celigo-ai-guidance:
             - |-
               ## FIELD BEHAVIOR
@@ -2123,6 +2141,32 @@ components:
           format: objectId
           x-celigo-refModel: httpconnectors
           description: HTTP connector backing this listener when the webhook is provided by an assistant/connector (e.g. Slack); set by the platform for connector-backed listeners.
+          x-celigo-ai-guidance:
+            - |-
+              The save stores the document as sent and copies nothing from the connector: a
+              listener posted with only `provider`, `key` and (optionally) `_httpConnectorId`
+              saves with no `verify`, `algorithm`, `encoding` or `header` (probed for `slack`
+              and `shopify`) — the API requires a credential for the provider and nothing else:
+              without `key` (and no `token`) `slack`, `shopify` and `github` each fail with 422
+              missing_required_field on `webhook.key` ("key is required for slack verification" /
+              "key is required for shopify verification" / "key is required for github
+              verification"), and a `slack` listener posted with `token` and no `key` saves. The
+              listener form fills the verification fields from the connector's
+              `supportedBy.export.preConfiguredFields` on every save (for Slack `verify: hmac`,
+              `algorithm: sha256`, `encoding: base64`, `header: X-Slack-Signature`); an API
+              caller that wants the stored document to match a form-saved one sends them itself.
+        _httpConnectorApiId:
+          type: string
+          format: objectId
+          x-celigo-refModel: httpconnectorapis
+          description: API of a multi-API connector (an entry of the connector's `apis[]`) this listener is bound to — the form's API type, offered in the Simple view; omit for single-API connectors and universal webhooks.
+          examples:
+            - 673702e2f367e6469401dcf6
+          x-celigo-ai-guidance:
+            - |-
+              Stored and echoed as sent on create and GET; a value that is not an ObjectId fails
+              the save with 422 `invalid_field` ("Invalid value … for field
+              'webhook._httpConnectorApiId'. Reason: BSONError.").
         requestMediaType:
           type: string
           enum:

package/dist/import.yml

@@ -4286,13 +4286,13 @@ components:
                       jsonPath:
                         type: string
                         description: |
-                          JSONPath into the source record that selects the
-                          data feeding this subrecord.  Semantics depend
+                          JSONPath from the source record root that selects
+                          the data feeding this subrecord.  Semantics depend
                           on placement:
                           * Line-level (on `lists[].fields[].`
-                            `subRecordMapping`) — often `$` to reuse
-                            the enclosing sublist line's row, or a path
-                            into a nested array on that row.
+                            `subRecordMapping`) — the array of lines the
+                            sublist iterates (`lineItems`); `$` only when
+                            each record is itself one line.
                           * Body-level (on `fields[].subRecordMapping`)
                             — a path into the source record root.
                           Defaults to `$`.
@@ -4484,9 +4484,10 @@ components:
                           type: boolean
                           description: |-
                             When true, this field is a key for matching the record's existing sublist lines: a
-                            mapped line updates the one existing line whose key fields hold the same values. `lists`
-                            says which records match lines, the keys used when no field sets `isKey`, and what a
-                            line that matches no line, or several, does.
+                            mapped line updates the one existing line whose key fields hold the same values —
+                            every key field must match, so several keys narrow the match. `lists` says which
+                            records match lines, the keys used when no field sets `isKey`, and what a line that
+                            matches no line, or several, does.
                         immutable:
                           type: boolean
                           description: When true, this field is only set on record creation, not on updates.
@@ -4565,13 +4566,19 @@ components:
                             jsonPath:
                               type: string
                               description: |
-                                JSONPath (relative to the current sublist
-                                line) to the rows that populate the
-                                subrecord.  Typically `$` when the
-                                subrecord data is carried on the same
-                                line item (iteration over the sublist
-                                has already selected the line).
-                                Defaults to `$`.
+                                Path from the source record root to the
+                                array of lines whose elements feed this
+                                subrecord — the same array the sublist
+                                iterates (`lineItems`, `items`); the n-th
+                                element populates the n-th sublist line.
+                                `$` only when each source record is itself
+                                one line. Defaults to `$`.
+                              x-celigo-ai-guidance:
+                                - |-
+                                  `$` on a record whose lines sit under a field renders no subrecord for any
+                                  line, and NetSuite rejects the first numbered line with `Please configure the
+                                  inventory detail in line N of the item list`; name the line array
+                                  (`lineItems`), never the current-line context.
                             mapping:
                               type: object
                               description: |
@@ -4682,6 +4689,11 @@ components:
                 with `MULTIPLE_LINES_WITH_SAME_KEYS` ("Multiple lines found with keys item=<value> ..."). A
                 line that matches none is added as a new line, which an item fulfillment's `item` sublist
                 refuses with `SSS_INVALID_SUBLIST_OPERATION`: its lines are its order's.
+
+                On a fulfillment created from an order, a kit's lot-, serial- or bin-managed components are
+                lines of their own under the kit's line, each with its own `line` and `orderline` (the
+                component's own order line) and `kitmemberof` holding the kit line's id; the inventory detail
+                belongs on those component lines, and a kit line refuses it.
               x-celigo-ai-guidance:
                 - |-
                   To make an update replace a sublist's lines, also map the body field
@@ -4696,6 +4708,24 @@ components:
                   field, or, on a fulfillment, the order line's id mapped to `orderline`. Keying on the item fails
                   with `MULTIPLE_LINES_WITH_SAME_KEYS` when an order holds the same item on two lines, and records
                   that already hold repeated lines fail the same way once a key is set.
+                - |-
+                  A key field is read from the existing lines, never written, so a read-only field keys as well
+                  as a writable one. The mapper's "Items : Line ID" is `line` (the fulfillment's own line number,
+                  equal to the order line only on a fresh full transform) and "Items : Line Number" is `linenum`;
+                  `orderline` and `kitmemberof` are not in its picker — type `item[*].orderline` /
+                  `item[*].kitmemberof` as the destination.
+                - |-
+                  Kit components on a fulfillment: the item is the only default key that reaches a component
+                  line, so a component two kit lines share fails with `MULTIPLE_LINES_WITH_SAME_KEYS`. Keying the
+                  component rows on the KIT's order line (`line` or `orderline`) selects the kit line instead and
+                  the save fails with `You cannot create an inventory detail for this item`. When the source
+                  carries the kit's order line on its component rows, keep the item as a key and add
+                  `item[*].kitmemberof` mapped from that line id as a second key, keep the kit rows in the list
+                  (their empty `kitmemberof` matches the kit line) with `item[*].celigo_ignore_current_line_invdetail_subrecord`
+                  true so no inventory detail is written on them, and build the inventory detail from each
+                  component row's own picks; component rows alone leave every kit line unfulfilled (`You must
+                  enter at least one line item for this transaction`). When the source can supply each
+                  component line's own order line id, key every row on `orderline` instead.
           x-celigo-agent:
             - mapping
         lookups:
@@ -8999,14 +9029,33 @@ components:
           x-enumDescriptions:
             pgp: Encrypt the file with PGP before it is written.
           description: |-
-            Encrypts the output file; omit it for an unencrypted file. `pgp` requires
-            `pgp.symmetricKeyAlgorithm` and a connection holding the recipient's public key
-            (`pgp.publicKey`) — without either the save fails with 422 `missing_required_field`.
-            The public-key check runs first: on a connection without one, any `encrypt` value,
-            `false` included, fails with 422 `missing_required_field` "pgp publicKey is required
-            when encrypt is selected to perform file encryption." before the value is checked.
-            Blob (file-transfer) imports follow the same rule and return `encrypt` and `pgp` even
-            without `file.type`.
+            Encrypts the file before it reaches the destination — a file generated from records
+            or, on a `blob: true` transfer, the existing file being moved; omit it for an
+            unencrypted file. `pgp` requires `pgp.symmetricKeyAlgorithm` and a connection holding
+            the recipient's public key (`pgp.publicKey`). Not observed in a run here; per the file
+            adaptor's code (IO-213945, the `blob: true` transfer path): with no `compressionFormat`,
+            a file over 200 MB fails the record before encryption with `pgp_file_size_exceeded`
+            ("The file size exceeds the maximum limit of 200 MB supported for PGP encryption." —
+            the adaptor's `errorStore.js` text); with `compressionFormat` set the adaptor skips that
+            pre-check (the compressed size is not known up front) and the encryption service
+            enforces its own 200 MB limit on the compressed file (`S3_FILE_SIZE_EXCEEDED`); a key
+            the platform cannot use fails with the PGP service's own code (`PGP_PUBLICKEY_INVALID` /
+            `PGP_PRIVATEKEY_INVALID` — "<operation> failed because the <key> is invalid."), and
+            `encryption_error` ("error in encrypting the file") only when the service returns no
+            code; the file is never written in clear and a transfer's encryption failure is not
+            retried automatically. A file generated from records meets the same encryption-service
+            limit with `S3_FILE_SIZE_EXCEEDED`.
+          x-celigo-ui-override: 'The transfer forms for FTP, S3, the on-premise file system and the cloud file providers (Box, Dropbox, Google Drive, Azure Blob Storage, Google Cloud Storage, Azure Data Lake Storage Gen2, Celigo file storage) offer the Encrypt files control in both modes (imports/subForms/fileAdvanced.js: ''pgpencrypt'' visible for inputMode records and blob, disabled until the connection holds a PGP key). The connection-side PGP section (connections/subForms/fileAdvanced.js) is mounted by ftp.js, s3.js, filesystem.js, celigoapis.ts, tp.js and the Box / Dropbox / Google Drive / Azure storage account custom HTTP forms; the Google Cloud Storage (httpFramework.js) and ADLS Gen2 (http.js) connection forms do not mount it, so on those two the key is set through the API. The AS2, VAN and NetSuite file cabinet import forms do not carry the control.'
+          x-celigo-ai-guidance:
+            - |-
+              Without `pgp.symmetricKeyAlgorithm` the save fails with 422 `missing_required_field` on
+              `file.pgp.symmetricKeyAlgorithm`; on a connection without `pgp.publicKey` it fails with
+              422 `missing_required_field` on `file.encrypt` ("pgp publicKey is required when encrypt
+              is selected to perform file encryption."), and that check runs first, for any value.
+            - |-
+              `true` and `false` are rejected with 422 `enum` — the field is the string `pgp`, never a
+              boolean. Blob transfers follow the same save rules and return `encrypt` and `pgp` on
+              reads even without `file.type`.
         csv:
           type: object
           description: CSV-specific configuration. Only used when `type` is `"csv"`.
@@ -9278,10 +9327,16 @@ components:
                 sha384: SHA-384 signing hash.
                 sha512: SHA-512 signing hash.
                 sha224: SHA-224 signing hash.
-              description: Hash algorithm used when signing the encrypted file; set only when the recipient requires a specific one.
+              description: Hash algorithm used when signing the encrypted file; set only when the recipient requires a signature, which also needs the connection's `pgp.privateKey` and `pgp.passphrase`.
               examples:
                 - sha256
                 - sha512
+              x-celigo-ai-guidance:
+                - |-
+                  On a connection without `pgp.privateKey` the save fails with 422
+                  `missing_required_field` on `file.pgp.hashAlgorithm` ("pgp privateKey is required
+                  when hashAlgorithm is selected to perform file signature."); leave it unset unless
+                  the connection holds the private key.
         skipRename:
           type: boolean
           description: |-

package/dist/mcp-server.yml

@@ -4891,26 +4891,36 @@ components:
     PGP:
       type: object
       description: |-
-        PGP encryption settings for file-based connections (ftp, s3, and similar). When set, files are
-        PGP-encrypted before upload and/or decrypted after download. Supply at least one of `publicKey`
-        (to encrypt outbound files) or `privateKey` (to decrypt inbound files); set `passphrase` whenever
-        `privateKey` is provided.
+        PGP keys and options for the file transports — `ftp`, `s3`, the on-premise file system and the
+        cloud file-provider connections such as Box, Dropbox, Google Drive, Azure Blob Storage and
+        Celigo file storage. `publicKey` encrypts the files the connection's imports write,
+        record-generated files and transferred (blob) files alike; `privateKey` with its `passphrase`
+        decrypts the files its exports read and signs encrypted output. Supply at least one of the two.
       properties:
         publicKey:
           type: string
           description: |-
-            ASCII-armored PGP public key used to encrypt outbound files before upload.
-            Set this when the connection sends encrypted files; omit it for decrypt-only connections.
+            ASCII-armored PGP public key of the recipient, used to encrypt every file an import on this
+            connection writes with `file.encrypt: pgp`; omit it for decrypt-only connections. Returned
+            in clear on reads.
           x-celigo-ai-guidance:
             - |-
-              Public key for JWT verification. Optional — used when the API requires
-              the public key to be registered for signature verification.
+              An import on this connection cannot save `file.encrypt: pgp` without it — the save fails
+              with 422 `missing_required_field` on `file.encrypt` ("pgp publicKey is required when
+              encrypt is selected to perform file encryption."); the import form disables its Encrypt
+              files control until the connection holds a key.
         privateKey:
           type: string
           writeOnly: true
           description: |-
             ASCII-armored PGP private key used to decrypt inbound files after download (encrypted at rest;
-            returned masked as `"******"`). Set this when the connection receives encrypted files.
+            returned masked as `"******"`). Set this when the connection receives encrypted files, or
+            when its imports sign what they encrypt (`file.pgp.hashAlgorithm`).
+          x-celigo-ai-guidance:
+            - |-
+              Signing needs it: an import that sets `file.pgp.hashAlgorithm` on a connection without a
+              private key fails to save with 422 `missing_required_field` on `file.pgp.hashAlgorithm`
+              ("pgp privateKey is required when hashAlgorithm is selected to perform file signature.").
         passphrase:
           type: string
           writeOnly: true
@@ -6692,10 +6702,11 @@ components:
         retryHeader:
           type: string
           description: |
-            HTTP response header name that contains the retry delay (in seconds) when rate-limited.
-
-            Defaults to "Retry-After" which is the HTTP standard. Only change this if the API
-            uses a non-standard header name for retry-after values.
+            Response header the retry reads for its wait once a response has been recognized
+            as rate-limited — a delay in seconds or an HTTP date. It only sets the wait: a
+            response carrying the header is not treated as throttled unless a status, header
+            or body rule under `rateLimit` matches it. Change it only when the API names its
+            retry-after header differently.
           default: Retry-After
         formType:
           type: string
@@ -7425,42 +7436,60 @@ components:
         rateLimit:
           type: object
           description: |
-            Rate limiting configuration. Defines how the system detects and handles
-            API rate limit responses.
-
-            When rate limiting is detected, the system pauses requests and waits for
-            the retry-after period before resuming. The retryHeader field on the parent
-            HTTP object controls which response header contains the wait time.
+            Rules for recognizing a throttled response. When any rule is set, every response
+            through the connection is checked against the status code, the header rules and
+            the body rule, and the first match marks the request rate-limited; the retry then
+            waits for the header named by the parent `retryHeader` (`Retry-After` by default).
+            A 429 is recognized with no rules at all; a 2xx response is recognized only through
+            a matching `failHeaders` rule or a matching `failPath` + `failValues` pair, which is
+            how APIs that throttle inside a 200 body (GraphQL, Shopify among them) are handled.
           properties:
             failStatusCode:
               type: number
               description: |
-                HTTP status code that indicates the API is rate-limiting requests.
-                Defaults to 429 (Too Many Requests) which is the HTTP standard.
-                Change only if the API uses a non-standard status code for rate limits.
+                Status code that marks a response rate-limited in place of the standard 429.
+                Set it only when the API throttles with another non-success code; a 2xx value
+                does not make successful responses count as throttled on its own.
               default: 429
             failPath:
               type: string
               description: |
-                JSON path or XPath to check in response bodies for rate limit indicators.
-                Used when APIs return 200 OK but embed rate limit errors in the response body.
+                JSON path or XPath to the body field that carries the API's throttle indicator,
+                for APIs that answer 200 with the error inside the body. Point at the field
+                itself (`errors.0.extensions.code`), not at the array or object around it, and
+                pair it with `failValues`, which supplies the values that mean "throttled".
               examples:
-                - errors[0].code
+                - errors.0.extensions.code
+              x-celigo-ai-guidance:
+                - |-
+                  Saves on its own (the probe shows a `failPath` with no `failValues` is accepted),
+                  and the documented contract recognizes a 200 as throttled only when `failValues`
+                  is set as well. For Shopify GraphQL the platform's own example is
+                  `errors.0.extensions.code` with `failValues: ["THROTTLED"]`.
             failValues:
               type: array
               items:
                 type: string
               description: |
-                Values at failPath that indicate rate limiting. Requires failPath to be set.
+                Values at `failPath` that mean the request was throttled; a match on any of them
+                marks the response rate-limited.
               examples:
-                - - rate_limit_exceeded
-                  - too_many_requests
+                - - THROTTLED
+                  - MAX_COST_EXCEEDED
+              x-celigo-ai-guidance:
+                - |-
+                  Needs `failPath`: `failValues` without it fails the save with 422
+                  `dependent_field` ("The field: failValues should not be specified without the
+                  field: failPath for the Connection.").
             failHeaders:
               type: array
               description: |
-                Response-header rules for detecting rate limiting, each a header `name` with an
-                optional `value`. A rule with an empty `name` fails the save with 422
-                `invalid_header_format`.
+                Response-header rules for recognizing a throttled response, each a header `name`
+                with an optional `value`. A rule with a `value` matches when the response header
+                carries that value — the stored text is compared with the header as received; a
+                rule with no `value` matches whenever the header is present at all, so a header
+                the API sends on every response (a remaining-quota counter) would mark every
+                response throttled — give such a header a value.
               items:
                 type: object
                 required:
@@ -7471,18 +7500,32 @@ components:
                     description: Response header the rule checks.
                   value:
                     type: string
-                    description: Header value the rule checks; omit to check the header alone.
+                    description: Header value the rule compares with the response header; omit to match on the header's presence alone. Stored as sent.
               examples:
                 - - name: X-RateLimit-Remaining
                     value: '0'
+              x-celigo-ai-guidance:
+                - |-
+                  A rule without a `name` fails the save with 422 `invalid_header_format`; a rule
+                  with a name and no value saves and matches on presence. The value is stored as
+                  sent and not validated at save time.
             limit:
               type: number
               minimum: 1
+              x-celigo-ui-override: Semantics mirror the connection form, which labels the field "Wait time between HTTP requests" and requires the value in milliseconds (fieldDefinitions/resources/connection.js 'http.rateLimit.limit').
               description: |
-                Maximum number of requests per rate-limit window. When set, the connection's
-                effective concurrency level must be 1 to ensure proper rate limit enforcement.
+                Minimum spacing between consecutive requests through the connection, in
+                milliseconds, for APIs that cap request rate rather than concurrency. It only
+                applies when the connection runs one request at a time.
               examples:
                 - 1000
+              x-celigo-ai-guidance:
+                - |-
+                  Saves only when `concurrencyLevel` is 1 — and, with `autoRecoverRateLimitErrors`
+                  on, `targetConcurrencyLevel` is 1 as well; otherwise the save fails with 422
+                  `invalid_concurrency_level` ("The field "connection.http.concurrencyLevel"
+                  should be set to 1 when the field "connection.http.rateLimit.limit" is
+                  populated."). A numeric string is stored as a number.
         headers:
           type: array
           description: |