@celigo/api-specs 0.2.76 → 0.2.77

package/dist/ai-agent.yml

@@ -128,7 +128,8 @@ paths:
         Hugging Face, DeepSeek, Cohere, and Groq — a block that does not match the
         provider is rejected. For a built-in provider, omit `_connectionId` to
         use platform-managed credentials or include it for BYOK; a catalog
-        provider saves without one but needs a BYOK connection to run.
+        provider needs a BYOK connection to save — without one the request
+        fails with 422 `connection_required` on `_connectionId`.
       operationId: createAiAgent
       tags:
         - AI Agents
@@ -679,8 +680,9 @@ components:
 
         A `_connectionId` on the parent import selects bring-your-own-key (BYOK)
         credentials. Without one, built-in providers run on platform-managed
-        credentials; catalog providers have no platform-managed credentials, so they
-        save without a connection but cannot run until one is attached.
+        credentials; catalog providers have no platform-managed credentials, so the
+        save requires one — without it the agent fails to save with 422
+        `connection_required` on `_connectionId`.
       required:
         - provider
       properties:
@@ -717,10 +719,11 @@ components:
               generic flat format — `model` and `modelOptions` directly on this object,
               never an `openai` or `litellm` block.
             - |-
-              Catalog providers are BYOK-only at run time: the agent saves without a
-              `_connectionId`, but its first run fails with 422 `invalid_request` ("No API
-              key configured for provider …"). Always attach an HTTP connection to the
-              vendor's API (token auth) when the provider is a catalog provider.
+              Catalog providers are BYOK-only, and the save enforces it: without a `_connectionId`
+              the agent fails to save with 422 `connection_required` on `_connectionId` ("No API
+              key is available for provider 'xai'. Add a connection for this provider with your
+              API key and select it on this agent."). Attach an HTTP connection to the vendor's
+              API (token auth) before saving a catalog-provider agent.
         model:
           type: string
           description: |-
@@ -732,11 +735,11 @@ components:
               Required for every catalog provider — omitting it or sending an empty string
               fails the save with 422 `missing_required_field`.
             - |-
-              Without a `_connectionId` on the parent import the model must be one the
-              catalog lists for the provider: an unknown id fails the save with 422
-              `model_not_found`, a listed-but-disabled id with 422 `model_disabled`. With a
-              `_connectionId` (BYOK) any model string saves — the server does not check it
-              against the catalog or the vendor.
+              The connection is checked before the model: without a `_connectionId` on the
+              parent import a catalog-provider agent fails to save with 422
+              `connection_required` whatever the model string (an unknown id included).
+              With a `_connectionId` (BYOK) any model string saves — the server does not
+              check it against the catalog or the vendor.
         modelOptions:
           type: object
           description: |-
@@ -1060,12 +1063,22 @@ components:
                         - manual
                         - json
                       x-enumDescriptions:
-                        manual: The schema was built field-by-field in the visual editor.
-                        json: The schema was pasted or edited as raw JSON.
+                        manual: The UI opens `jsonSchema` in the visual field-by-field editor
+                        json: The UI opens `jsonSchema` in the raw JSON editor
                       description: |-
-                        How the structured-output schema was authored in the UI.
-                        Editor state only — it does not change how `jsonSchema` is
-                        sent to the provider.
+                        Which editor the UI opens `jsonSchema` in; the schema sent to the provider
+                        is the same either way, and the field is only meaningful when `type` is
+                        "json_schema". Unset opens the visual editor, and an edit there rebuilds
+                        `jsonSchema` from the field list, keeping only `type`, `properties`,
+                        `required`, `items`, `description`, `enum`, `pattern`, length and numeric
+                        bounds, `multipleOf`, `minItems`/`maxItems` and a `"null"` type — other
+                        keywords are dropped without a prompt, and `integer` becomes `number`.
+                      x-celigo-ai-guidance:
+                        - |-
+                          Set `json` on a schema written as raw JSON; keep a user's `manual` and stay
+                          inside the keywords the visual editor keeps. A full PUT that omits the field
+                          clears it, and a value outside the enum fails the save with 422 `enum` on
+                          `aiAgent.openai.output.format.schemaMode`.
                     name:
                       type: string
                       description: Name for the output format (used with json_schema)
@@ -1418,12 +1431,22 @@ components:
                     - manual
                     - json
                   x-enumDescriptions:
-                    manual: The schema was built field-by-field in the visual editor.
-                    json: The schema was pasted or edited as raw JSON.
+                    manual: The UI opens `jsonSchema` in the visual field-by-field editor
+                    json: The UI opens `jsonSchema` in the raw JSON editor
                   description: |-
-                    How the structured-output schema was authored in the UI. Editor
-                    state only — it does not change how `jsonSchema` is sent to the
-                    provider.
+                    Which editor the UI opens `jsonSchema` in; the schema sent to the provider is
+                    the same either way, and the field is only meaningful when `type` is
+                    "json_schema". Unset opens the visual editor, and an edit there rebuilds
+                    `jsonSchema` from the field list, keeping only `type`, `properties`, `required`,
+                    `items`, `description`, `enum`, `pattern`, length and numeric bounds,
+                    `multipleOf`, `minItems`/`maxItems` and a `"null"` type — other keywords are
+                    dropped without a prompt, and `integer` becomes `number`.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Set `json` on a schema written as raw JSON; keep a user's `manual` and stay inside
+                      the keywords the visual editor keeps. A full PUT that omits the field clears it,
+                      and a value outside the enum fails the save with 422 `enum` on
+                      `aiAgent.litellm.responseFormat.schemaMode`.
                 name:
                   type: string
                   description: Name for the output format (used with json_schema).
@@ -5225,8 +5248,9 @@ components:
             Connection for BYOK (bring your own key) — an HTTP connection to the vendor's API.
             Optional for the built-in providers (`openai`, `gemini`, `anthropic`), which run on
             platform-managed credentials when it is omitted. Catalog providers (`mistral`, `xai`,
-            `huggingface`, `deepseek`, `cohere`, `groq`) have no platform-managed credentials: the agent
-            saves without one but cannot run until it is set.
+            `huggingface`, `deepseek`, `cohere`, `groq`) have no platform-managed credentials: the save
+            requires it — without one the agent fails to save with 422 `connection_required` on
+            `_connectionId`.
           examples:
             - 662aaa6576bf4040548dbbe4
         _integrationId:

package/dist/guardrail.yml

@@ -602,8 +602,9 @@ components:
 
         A `_connectionId` on the parent import selects bring-your-own-key (BYOK)
         credentials. Without one, built-in providers run on platform-managed
-        credentials; catalog providers have no platform-managed credentials, so they
-        save without a connection but cannot run until one is attached.
+        credentials; catalog providers have no platform-managed credentials, so the
+        save requires one — without it the guardrail fails to save with 422
+        `connection_required` on `_connectionId`.
       x-celigo-ai-guidance:
         - |-
           Do not send `tools` on any block. A non-empty array at `tools`, `openai.tools`,
@@ -646,10 +647,11 @@ components:
               generic flat format — `model` and `modelOptions` directly on this object,
               never an `openai` or `litellm` block.
             - |-
-              Catalog providers are BYOK-only at run time: the guardrail saves without a
-              `_connectionId`, but its first run fails with 422 `invalid_request` ("No API
-              key configured for provider …"). Always attach an HTTP connection to the
-              vendor's API (token auth) when the provider is a catalog provider.
+              Catalog providers are BYOK-only, and the save enforces it: without a `_connectionId`
+              the guardrail fails to save with 422 `connection_required` on `_connectionId` ("No
+              API key is available for provider 'xai'. Add a connection for this provider with
+              your API key and select it on this agent."). Attach an HTTP connection to the
+              vendor's API (token auth) before saving a catalog-provider guardrail.
         model:
           type: string
           description: |-
@@ -661,11 +663,11 @@ components:
               Required for every catalog provider — omitting it or sending an empty string
               fails the save with 422 `missing_required_field`.
             - |-
-              Without a `_connectionId` on the parent import the model must be one the
-              catalog lists for the provider: an unknown id fails the save with 422
-              `model_not_found`, a listed-but-disabled id with 422 `model_disabled`. With a
-              `_connectionId` (BYOK) any model string saves — the server does not check it
-              against the catalog or the vendor.
+              The connection is checked before the model: without a `_connectionId` on the
+              parent import a catalog-provider guardrail fails to save with 422
+              `connection_required` whatever the model string (an unknown id included).
+              With a `_connectionId` (BYOK) any model string saves — the server does not
+              check it against the catalog or the vendor.
         modelOptions:
           type: object
           description: |-
@@ -930,12 +932,17 @@ components:
                         - manual
                         - json
                       x-enumDescriptions:
-                        manual: The schema was built field-by-field in the visual editor.
-                        json: The schema was pasted or edited as raw JSON.
+                        manual: The schema editor opens `jsonSchema` in the visual field-by-field view
+                        json: The schema editor opens `jsonSchema` in the raw JSON view
                       description: |-
-                        How the structured-output schema was authored in the UI.
-                        Editor state only — it does not change how `jsonSchema` is
-                        sent to the provider.
+                        Which view a schema editor opens `jsonSchema` in; the schema sent to the
+                        provider is the same either way. Stored and echoed on guardrails for parity
+                        with the AI-agent format block — the guardrail form does not set it today.
+                      x-celigo-ai-guidance:
+                        - |-
+                          Resend the stored value on every update — a full PUT that omits the field
+                          clears it — and never invent one: a value outside the enum fails the save with
+                          422 `enum` on `guardrail.aiAgent.openai.output.format.schemaMode`.
                     name:
                       type: string
                       description: Name for the output format (used with json_schema)
@@ -1124,12 +1131,17 @@ components:
                     - manual
                     - json
                   x-enumDescriptions:
-                    manual: The schema was built field-by-field in the visual editor.
-                    json: The schema was pasted or edited as raw JSON.
+                    manual: The schema editor opens `jsonSchema` in the visual field-by-field view
+                    json: The schema editor opens `jsonSchema` in the raw JSON view
                   description: |-
-                    How the structured-output schema was authored in the UI. Editor
-                    state only — it does not change how `jsonSchema` is sent to the
-                    provider.
+                    Which view a schema editor opens `jsonSchema` in; the schema sent to the provider
+                    is the same either way. Stored and echoed on guardrails for parity with the
+                    AI-agent format block — the guardrail form does not set it today.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Resend the stored value on every update — a full PUT that omits the field clears
+                      it — and never invent one: a value outside the enum fails the save with 422 `enum`
+                      on `guardrail.aiAgent.litellm.responseFormat.schemaMode`.
                 name:
                   type: string
                   description: Name for the output format (used with json_schema).

package/dist/import.yml

@@ -9046,8 +9046,9 @@ components:
 
         A `_connectionId` on the parent import selects bring-your-own-key (BYOK)
         credentials. Without one, built-in providers run on platform-managed
-        credentials; catalog providers have no platform-managed credentials, so they
-        save without a connection but cannot run until one is attached.
+        credentials; catalog providers have no platform-managed credentials, so the
+        save requires one — without it the agent fails to save with 422
+        `connection_required` on `_connectionId`.
       required:
         - provider
       properties:
@@ -9084,10 +9085,11 @@ components:
               generic flat format — `model` and `modelOptions` directly on this object,
               never an `openai` or `litellm` block.
             - |-
-              Catalog providers are BYOK-only at run time: the agent saves without a
-              `_connectionId`, but its first run fails with 422 `invalid_request` ("No API
-              key configured for provider …"). Always attach an HTTP connection to the
-              vendor's API (token auth) when the provider is a catalog provider.
+              Catalog providers are BYOK-only, and the save enforces it: without a `_connectionId`
+              the agent fails to save with 422 `connection_required` on `_connectionId` ("No API
+              key is available for provider 'xai'. Add a connection for this provider with your
+              API key and select it on this agent."). Attach an HTTP connection to the vendor's
+              API (token auth) before saving a catalog-provider agent.
         model:
           type: string
           description: |-
@@ -9099,11 +9101,11 @@ components:
               Required for every catalog provider — omitting it or sending an empty string
               fails the save with 422 `missing_required_field`.
             - |-
-              Without a `_connectionId` on the parent import the model must be one the
-              catalog lists for the provider: an unknown id fails the save with 422
-              `model_not_found`, a listed-but-disabled id with 422 `model_disabled`. With a
-              `_connectionId` (BYOK) any model string saves — the server does not check it
-              against the catalog or the vendor.
+              The connection is checked before the model: without a `_connectionId` on the
+              parent import a catalog-provider agent fails to save with 422
+              `connection_required` whatever the model string (an unknown id included).
+              With a `_connectionId` (BYOK) any model string saves — the server does not
+              check it against the catalog or the vendor.
         modelOptions:
           type: object
           description: |-
@@ -9427,12 +9429,22 @@ components:
                         - manual
                         - json
                       x-enumDescriptions:
-                        manual: The schema was built field-by-field in the visual editor.
-                        json: The schema was pasted or edited as raw JSON.
+                        manual: The UI opens `jsonSchema` in the visual field-by-field editor
+                        json: The UI opens `jsonSchema` in the raw JSON editor
                       description: |-
-                        How the structured-output schema was authored in the UI.
-                        Editor state only — it does not change how `jsonSchema` is
-                        sent to the provider.
+                        Which editor the UI opens `jsonSchema` in; the schema sent to the provider
+                        is the same either way, and the field is only meaningful when `type` is
+                        "json_schema". Unset opens the visual editor, and an edit there rebuilds
+                        `jsonSchema` from the field list, keeping only `type`, `properties`,
+                        `required`, `items`, `description`, `enum`, `pattern`, length and numeric
+                        bounds, `multipleOf`, `minItems`/`maxItems` and a `"null"` type — other
+                        keywords are dropped without a prompt, and `integer` becomes `number`.
+                      x-celigo-ai-guidance:
+                        - |-
+                          Set `json` on a schema written as raw JSON; keep a user's `manual` and stay
+                          inside the keywords the visual editor keeps. A full PUT that omits the field
+                          clears it, and a value outside the enum fails the save with 422 `enum` on
+                          `aiAgent.openai.output.format.schemaMode`.
                     name:
                       type: string
                       description: Name for the output format (used with json_schema)
@@ -9785,12 +9797,22 @@ components:
                     - manual
                     - json
                   x-enumDescriptions:
-                    manual: The schema was built field-by-field in the visual editor.
-                    json: The schema was pasted or edited as raw JSON.
+                    manual: The UI opens `jsonSchema` in the visual field-by-field editor
+                    json: The UI opens `jsonSchema` in the raw JSON editor
                   description: |-
-                    How the structured-output schema was authored in the UI. Editor
-                    state only — it does not change how `jsonSchema` is sent to the
-                    provider.
+                    Which editor the UI opens `jsonSchema` in; the schema sent to the provider is
+                    the same either way, and the field is only meaningful when `type` is
+                    "json_schema". Unset opens the visual editor, and an edit there rebuilds
+                    `jsonSchema` from the field list, keeping only `type`, `properties`, `required`,
+                    `items`, `description`, `enum`, `pattern`, length and numeric bounds,
+                    `multipleOf`, `minItems`/`maxItems` and a `"null"` type — other keywords are
+                    dropped without a prompt, and `integer` becomes `number`.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Set `json` on a schema written as raw JSON; keep a user's `manual` and stay inside
+                      the keywords the visual editor keeps. A full PUT that omits the field clears it,
+                      and a value outside the enum fails the save with 422 `enum` on
+                      `aiAgent.litellm.responseFormat.schemaMode`.
                 name:
                   type: string
                   description: Name for the output format (used with json_schema).
@@ -10467,8 +10489,9 @@ components:
 
         A `_connectionId` on the parent import selects bring-your-own-key (BYOK)
         credentials. Without one, built-in providers run on platform-managed
-        credentials; catalog providers have no platform-managed credentials, so they
-        save without a connection but cannot run until one is attached.
+        credentials; catalog providers have no platform-managed credentials, so the
+        save requires one — without it the guardrail fails to save with 422
+        `connection_required` on `_connectionId`.
       x-celigo-ai-guidance:
         - |-
           Do not send `tools` on any block. A non-empty array at `tools`, `openai.tools`,
@@ -10511,10 +10534,11 @@ components:
               generic flat format — `model` and `modelOptions` directly on this object,
               never an `openai` or `litellm` block.
             - |-
-              Catalog providers are BYOK-only at run time: the guardrail saves without a
-              `_connectionId`, but its first run fails with 422 `invalid_request` ("No API
-              key configured for provider …"). Always attach an HTTP connection to the
-              vendor's API (token auth) when the provider is a catalog provider.
+              Catalog providers are BYOK-only, and the save enforces it: without a `_connectionId`
+              the guardrail fails to save with 422 `connection_required` on `_connectionId` ("No
+              API key is available for provider 'xai'. Add a connection for this provider with
+              your API key and select it on this agent."). Attach an HTTP connection to the
+              vendor's API (token auth) before saving a catalog-provider guardrail.
         model:
           type: string
           description: |-
@@ -10526,11 +10550,11 @@ components:
               Required for every catalog provider — omitting it or sending an empty string
               fails the save with 422 `missing_required_field`.
             - |-
-              Without a `_connectionId` on the parent import the model must be one the
-              catalog lists for the provider: an unknown id fails the save with 422
-              `model_not_found`, a listed-but-disabled id with 422 `model_disabled`. With a
-              `_connectionId` (BYOK) any model string saves — the server does not check it
-              against the catalog or the vendor.
+              The connection is checked before the model: without a `_connectionId` on the
+              parent import a catalog-provider guardrail fails to save with 422
+              `connection_required` whatever the model string (an unknown id included).
+              With a `_connectionId` (BYOK) any model string saves — the server does not
+              check it against the catalog or the vendor.
         modelOptions:
           type: object
           description: |-
@@ -10795,12 +10819,17 @@ components:
                         - manual
                         - json
                       x-enumDescriptions:
-                        manual: The schema was built field-by-field in the visual editor.
-                        json: The schema was pasted or edited as raw JSON.
+                        manual: The schema editor opens `jsonSchema` in the visual field-by-field view
+                        json: The schema editor opens `jsonSchema` in the raw JSON view
                       description: |-
-                        How the structured-output schema was authored in the UI.
-                        Editor state only — it does not change how `jsonSchema` is
-                        sent to the provider.
+                        Which view a schema editor opens `jsonSchema` in; the schema sent to the
+                        provider is the same either way. Stored and echoed on guardrails for parity
+                        with the AI-agent format block — the guardrail form does not set it today.
+                      x-celigo-ai-guidance:
+                        - |-
+                          Resend the stored value on every update — a full PUT that omits the field
+                          clears it — and never invent one: a value outside the enum fails the save with
+                          422 `enum` on `guardrail.aiAgent.openai.output.format.schemaMode`.
                     name:
                       type: string
                       description: Name for the output format (used with json_schema)
@@ -10989,12 +11018,17 @@ components:
                     - manual
                     - json
                   x-enumDescriptions:
-                    manual: The schema was built field-by-field in the visual editor.
-                    json: The schema was pasted or edited as raw JSON.
+                    manual: The schema editor opens `jsonSchema` in the visual field-by-field view
+                    json: The schema editor opens `jsonSchema` in the raw JSON view
                   description: |-
-                    How the structured-output schema was authored in the UI. Editor
-                    state only — it does not change how `jsonSchema` is sent to the
-                    provider.
+                    Which view a schema editor opens `jsonSchema` in; the schema sent to the provider
+                    is the same either way. Stored and echoed on guardrails for parity with the
+                    AI-agent format block — the guardrail form does not set it today.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Resend the stored value on every update — a full PUT that omits the field clears
+                      it — and never invent one: a value outside the enum fails the save with 422 `enum`
+                      on `guardrail.aiAgent.litellm.responseFormat.schemaMode`.
                 name:
                   type: string
                   description: Name for the output format (used with json_schema).

package/dist/tool.yml

@@ -5577,11 +5577,25 @@ components:
             - manual
             - json
           x-enumDescriptions:
-            manual: The input schema was built field-by-field in the visual editor
-            json: The input schema was pasted or edited as raw JSON
+            manual: The UI opens `schema` in the visual field-by-field editor
+            json: The UI opens `schema` in the raw JSON editor
           description: |-
-            How `schema` was authored in the UI. Editor state only — it does not change how
-            the schema validates invocation input. Present when set.
+            Which editor the UI opens `schema` in; invocation input validates the same either way.
+            Unset opens the visual editor, and an edit there rebuilds `schema` from the field list,
+            keeping only `type`, `properties`, `required`, `items`, `description`, `enum`, `pattern`,
+            `minLength`/`maxLength`, `minimum`/`maximum`, `exclusiveMinimum`/`exclusiveMaximum`,
+            `multipleOf`, `minItems`/`maxItems` and a `"null"` type — `format`, `const`, `default`,
+            `additionalProperties`, `$ref` and `allOf`/`anyOf`/`oneOf`/`if` are dropped without a
+            prompt, and `integer` becomes `number`.
+          x-celigo-ai-guidance:
+            - |-
+              Set `json` on any schema written as raw JSON so the UI opens the JSON editor and warns
+              before a switch to the visual editor can drop keywords; keep `manual` on a schema a
+              user built in the visual editor and stay inside the keywords it keeps.
+            - |-
+              A full PUT that omits this field clears it — resend the stored value on every update.
+              PATCH rejects the path ("/input/schemaMode is not a whitelisted property"), and a value
+              outside the enum fails the save with 422 `enum` on `input.schemaMode`.
           examples:
             - json
         transform:
@@ -5662,11 +5676,25 @@ components:
             - manual
             - json
           x-enumDescriptions:
-            manual: The output schema was built field-by-field in the visual editor
-            json: The output schema was pasted or edited as raw JSON
+            manual: The UI opens `schema` in the visual field-by-field editor
+            json: The UI opens `schema` in the raw JSON editor
           description: |-
-            How `schema` was authored in the UI. Editor state only — it does not change how
-            the output is produced. Present when set.
+            Which editor the UI opens `schema` in; the output validates the same either way. Unset
+            opens the visual editor, and an edit there rebuilds `schema` from the field list, keeping
+            only `type`, `properties`, `required`, `items`, `description`, `enum`, `pattern`,
+            `minLength`/`maxLength`, `minimum`/`maximum`, `exclusiveMinimum`/`exclusiveMaximum`,
+            `multipleOf`, `minItems`/`maxItems` and a `"null"` type — `format`, `const`, `default`,
+            `additionalProperties`, `$ref` and `allOf`/`anyOf`/`oneOf`/`if` are dropped without a
+            prompt, and `integer` becomes `number`.
+          x-celigo-ai-guidance:
+            - |-
+              Set `json` on any schema written as raw JSON so the UI opens the JSON editor and warns
+              before a switch to the visual editor can drop keywords; keep `manual` on a schema a
+              user built in the visual editor and stay inside the keywords it keeps.
+            - |-
+              A full PUT that omits this field clears it — resend the stored value on every update.
+              PATCH rejects the path ("/output/schemaMode is not a whitelisted property"), and a
+              value outside the enum fails the save with 422 `enum` on `output.schemaMode`.
           examples:
             - manual
         mappings:
@@ -19416,8 +19444,9 @@ components:
 
         A `_connectionId` on the parent import selects bring-your-own-key (BYOK)
         credentials. Without one, built-in providers run on platform-managed
-        credentials; catalog providers have no platform-managed credentials, so they
-        save without a connection but cannot run until one is attached.
+        credentials; catalog providers have no platform-managed credentials, so the
+        save requires one — without it the agent fails to save with 422
+        `connection_required` on `_connectionId`.
       required:
         - provider
       properties:
@@ -19454,10 +19483,11 @@ components:
               generic flat format — `model` and `modelOptions` directly on this object,
               never an `openai` or `litellm` block.
             - |-
-              Catalog providers are BYOK-only at run time: the agent saves without a
-              `_connectionId`, but its first run fails with 422 `invalid_request` ("No API
-              key configured for provider …"). Always attach an HTTP connection to the
-              vendor's API (token auth) when the provider is a catalog provider.
+              Catalog providers are BYOK-only, and the save enforces it: without a `_connectionId`
+              the agent fails to save with 422 `connection_required` on `_connectionId` ("No API
+              key is available for provider 'xai'. Add a connection for this provider with your
+              API key and select it on this agent."). Attach an HTTP connection to the vendor's
+              API (token auth) before saving a catalog-provider agent.
         model:
           type: string
           description: |-
@@ -19469,11 +19499,11 @@ components:
               Required for every catalog provider — omitting it or sending an empty string
               fails the save with 422 `missing_required_field`.
             - |-
-              Without a `_connectionId` on the parent import the model must be one the
-              catalog lists for the provider: an unknown id fails the save with 422
-              `model_not_found`, a listed-but-disabled id with 422 `model_disabled`. With a
-              `_connectionId` (BYOK) any model string saves — the server does not check it
-              against the catalog or the vendor.
+              The connection is checked before the model: without a `_connectionId` on the
+              parent import a catalog-provider agent fails to save with 422
+              `connection_required` whatever the model string (an unknown id included).
+              With a `_connectionId` (BYOK) any model string saves — the server does not
+              check it against the catalog or the vendor.
         modelOptions:
           type: object
           description: |-
@@ -19797,12 +19827,22 @@ components:
                         - manual
                         - json
                       x-enumDescriptions:
-                        manual: The schema was built field-by-field in the visual editor.
-                        json: The schema was pasted or edited as raw JSON.
+                        manual: The UI opens `jsonSchema` in the visual field-by-field editor
+                        json: The UI opens `jsonSchema` in the raw JSON editor
                       description: |-
-                        How the structured-output schema was authored in the UI.
-                        Editor state only — it does not change how `jsonSchema` is
-                        sent to the provider.
+                        Which editor the UI opens `jsonSchema` in; the schema sent to the provider
+                        is the same either way, and the field is only meaningful when `type` is
+                        "json_schema". Unset opens the visual editor, and an edit there rebuilds
+                        `jsonSchema` from the field list, keeping only `type`, `properties`,
+                        `required`, `items`, `description`, `enum`, `pattern`, length and numeric
+                        bounds, `multipleOf`, `minItems`/`maxItems` and a `"null"` type — other
+                        keywords are dropped without a prompt, and `integer` becomes `number`.
+                      x-celigo-ai-guidance:
+                        - |-
+                          Set `json` on a schema written as raw JSON; keep a user's `manual` and stay
+                          inside the keywords the visual editor keeps. A full PUT that omits the field
+                          clears it, and a value outside the enum fails the save with 422 `enum` on
+                          `aiAgent.openai.output.format.schemaMode`.
                     name:
                       type: string
                       description: Name for the output format (used with json_schema)
@@ -20155,12 +20195,22 @@ components:
                     - manual
                     - json
                   x-enumDescriptions:
-                    manual: The schema was built field-by-field in the visual editor.
-                    json: The schema was pasted or edited as raw JSON.
+                    manual: The UI opens `jsonSchema` in the visual field-by-field editor
+                    json: The UI opens `jsonSchema` in the raw JSON editor
                   description: |-
-                    How the structured-output schema was authored in the UI. Editor
-                    state only — it does not change how `jsonSchema` is sent to the
-                    provider.
+                    Which editor the UI opens `jsonSchema` in; the schema sent to the provider is
+                    the same either way, and the field is only meaningful when `type` is
+                    "json_schema". Unset opens the visual editor, and an edit there rebuilds
+                    `jsonSchema` from the field list, keeping only `type`, `properties`, `required`,
+                    `items`, `description`, `enum`, `pattern`, length and numeric bounds,
+                    `multipleOf`, `minItems`/`maxItems` and a `"null"` type — other keywords are
+                    dropped without a prompt, and `integer` becomes `number`.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Set `json` on a schema written as raw JSON; keep a user's `manual` and stay inside
+                      the keywords the visual editor keeps. A full PUT that omits the field clears it,
+                      and a value outside the enum fails the save with 422 `enum` on
+                      `aiAgent.litellm.responseFormat.schemaMode`.
                 name:
                   type: string
                   description: Name for the output format (used with json_schema).
@@ -20837,8 +20887,9 @@ components:
 
         A `_connectionId` on the parent import selects bring-your-own-key (BYOK)
         credentials. Without one, built-in providers run on platform-managed
-        credentials; catalog providers have no platform-managed credentials, so they
-        save without a connection but cannot run until one is attached.
+        credentials; catalog providers have no platform-managed credentials, so the
+        save requires one — without it the guardrail fails to save with 422
+        `connection_required` on `_connectionId`.
       x-celigo-ai-guidance:
         - |-
           Do not send `tools` on any block. A non-empty array at `tools`, `openai.tools`,
@@ -20881,10 +20932,11 @@ components:
               generic flat format — `model` and `modelOptions` directly on this object,
               never an `openai` or `litellm` block.
             - |-
-              Catalog providers are BYOK-only at run time: the guardrail saves without a
-              `_connectionId`, but its first run fails with 422 `invalid_request` ("No API
-              key configured for provider …"). Always attach an HTTP connection to the
-              vendor's API (token auth) when the provider is a catalog provider.
+              Catalog providers are BYOK-only, and the save enforces it: without a `_connectionId`
+              the guardrail fails to save with 422 `connection_required` on `_connectionId` ("No
+              API key is available for provider 'xai'. Add a connection for this provider with
+              your API key and select it on this agent."). Attach an HTTP connection to the
+              vendor's API (token auth) before saving a catalog-provider guardrail.
         model:
           type: string
           description: |-
@@ -20896,11 +20948,11 @@ components:
               Required for every catalog provider — omitting it or sending an empty string
               fails the save with 422 `missing_required_field`.
             - |-
-              Without a `_connectionId` on the parent import the model must be one the
-              catalog lists for the provider: an unknown id fails the save with 422
-              `model_not_found`, a listed-but-disabled id with 422 `model_disabled`. With a
-              `_connectionId` (BYOK) any model string saves — the server does not check it
-              against the catalog or the vendor.
+              The connection is checked before the model: without a `_connectionId` on the
+              parent import a catalog-provider guardrail fails to save with 422
+              `connection_required` whatever the model string (an unknown id included).
+              With a `_connectionId` (BYOK) any model string saves — the server does not
+              check it against the catalog or the vendor.
         modelOptions:
           type: object
           description: |-
@@ -21165,12 +21217,17 @@ components:
                         - manual
                         - json
                       x-enumDescriptions:
-                        manual: The schema was built field-by-field in the visual editor.
-                        json: The schema was pasted or edited as raw JSON.
+                        manual: The schema editor opens `jsonSchema` in the visual field-by-field view
+                        json: The schema editor opens `jsonSchema` in the raw JSON view
                       description: |-
-                        How the structured-output schema was authored in the UI.
-                        Editor state only — it does not change how `jsonSchema` is
-                        sent to the provider.
+                        Which view a schema editor opens `jsonSchema` in; the schema sent to the
+                        provider is the same either way. Stored and echoed on guardrails for parity
+                        with the AI-agent format block — the guardrail form does not set it today.
+                      x-celigo-ai-guidance:
+                        - |-
+                          Resend the stored value on every update — a full PUT that omits the field
+                          clears it — and never invent one: a value outside the enum fails the save with
+                          422 `enum` on `guardrail.aiAgent.openai.output.format.schemaMode`.
                     name:
                       type: string
                       description: Name for the output format (used with json_schema)
@@ -21359,12 +21416,17 @@ components:
                     - manual
                     - json
                   x-enumDescriptions:
-                    manual: The schema was built field-by-field in the visual editor.
-                    json: The schema was pasted or edited as raw JSON.
+                    manual: The schema editor opens `jsonSchema` in the visual field-by-field view
+                    json: The schema editor opens `jsonSchema` in the raw JSON view
                   description: |-
-                    How the structured-output schema was authored in the UI. Editor
-                    state only — it does not change how `jsonSchema` is sent to the
-                    provider.
+                    Which view a schema editor opens `jsonSchema` in; the schema sent to the provider
+                    is the same either way. Stored and echoed on guardrails for parity with the
+                    AI-agent format block — the guardrail form does not set it today.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Resend the stored value on every update — a full PUT that omits the field clears
+                      it — and never invent one: a value outside the enum fails the save with 422 `enum`
+                      on `guardrail.aiAgent.litellm.responseFormat.schemaMode`.
                 name:
                   type: string
                   description: Name for the output format (used with json_schema).

package/package.json

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

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "1d2dcf0",
+		"iasCommit": "2fa4fd0",
 		"generatedAt": "2026-10-06"
 	},
 	"roots": {