@celigo/api-specs 0.2.1

package/dist/guardrail.yml

@@ -0,0 +1,2763 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Guardrails
+  description: Manage guardrail safety and compliance checks for integrations.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: Guardrails
+    description: |-
+      Guardrails are safety and compliance checks that evaluate data flowing
+      through integrations — detecting PII, moderating content, or applying
+      custom AI-powered rules.
+
+      Guardrails are import resources with `adaptorType: GuardrailImport`. All
+      CRUD operations use the `/v1/imports` endpoints. The `guardrail` object
+      holds the type-specific configuration.
+
+      ## Guardrail schema
+
+      {% openapi-schemas spec="guardrail" schemas="Guardrail" grouped="true" %}
+paths:
+  /v1/imports:
+    get:
+      x-internal: false
+      summary: List guardrails
+      description: |-
+        Returns all imports in the account, not just guardrails. Filter
+        client-side by `adaptorType: "GuardrailImport"` to isolate
+        guardrails.
+      operationId: listGuardrails
+      tags:
+        - Guardrails
+      parameters:
+        - $ref: '#/components/parameters/Include'
+        - $ref: '#/components/parameters/Exclude'
+      responses:
+        '200':
+          description: Successfully retrieved list of imports
+          headers:
+            Link:
+              description: |
+                RFC-5988 pagination links. When more pages remain, includes a `<...>; rel="next"` entry;
+                absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Guardrail'
+              examples:
+                guardrail-list:
+                  summary: Response filtered to guardrails
+                  value:
+                    - _id: 69eb9f5078dbae2f1bb05f89
+                      createdAt: '2026-04-24T16:50:24.073Z'
+                      lastModified: '2026-05-02T15:46:24.249Z'
+                      name: PII Scanner
+                      apiIdentifier: i39ee734f7
+                      sandbox: false
+                      lookups: []
+                      adaptorType: GuardrailImport
+                      guardrail:
+                        type: pii
+                        confidenceThreshold: 0.7
+                        pii:
+                          entities:
+                            - email_address
+                            - phone_number
+                            - us_social_security_number
+                          mask: true
+                    - _id: 69eb9f666fbf339ed3bc66c3
+                      createdAt: '2026-04-24T16:50:46.439Z'
+                      lastModified: '2026-04-24T16:50:53.525Z'
+                      name: Content Moderator
+                      _connectionId: 68ae48d6b5f755d2dd38c294
+                      apiIdentifier: i6a7acf995
+                      sandbox: false
+                      lookups: []
+                      adaptorType: GuardrailImport
+                      guardrail:
+                        type: moderation
+                        confidenceThreshold: 0.7
+                        moderation:
+                          categories:
+                            - hate
+                            - violence
+                            - harassment
+        '204':
+          description: No imports exist in the account
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+    post:
+      x-internal: false
+      summary: Create a guardrail
+      description: |-
+        Creates a new guardrail import. `_connectionId` is only needed for
+        BYOK `ai_agent` guardrails.
+      operationId: createGuardrail
+      tags:
+        - Guardrails
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              pii-guardrail:
+                summary: PII detection with masking
+                value:
+                  name: PII Scanner
+                  adaptorType: GuardrailImport
+                  guardrail:
+                    type: pii
+                    confidenceThreshold: 0.7
+                    pii:
+                      entities:
+                        - email_address
+                        - phone_number
+                        - us_social_security_number
+                      mask: true
+              moderation-guardrail:
+                summary: Content moderation
+                value:
+                  name: Content Moderator
+                  adaptorType: GuardrailImport
+                  guardrail:
+                    type: moderation
+                    confidenceThreshold: 0.7
+                    moderation:
+                      categories:
+                        - hate
+                        - violence
+                        - harassment
+              ai-agent-guardrail:
+                summary: AI agent with BYOK connection
+                value:
+                  name: Custom Validator
+                  adaptorType: GuardrailImport
+                  _connectionId: 68ae48d6b5f755d2dd38c294
+                  guardrail:
+                    type: ai_agent
+                    confidenceThreshold: 0.7
+                    aiAgent:
+                      provider: openai
+                      openai:
+                        instructions: Validate that each record has a non-empty email field and a valid country code.
+                        model: gpt-4.1-mini
+      responses:
+        '201':
+          description: Guardrail created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Guardrail'
+              examples:
+                pii-created:
+                  summary: Newly created PII guardrail
+                  value:
+                    _id: 6a1cfd72c7867992e6d5b021
+                    createdAt: '2026-06-01T03:33:06.758Z'
+                    lastModified: '2026-06-01T03:33:06.851Z'
+                    name: PII Scanner
+                    apiIdentifier: i894602e87
+                    lookups: []
+                    adaptorType: GuardrailImport
+                    guardrail:
+                      type: pii
+                      confidenceThreshold: 0.7
+                      pii:
+                        entities:
+                          - email_address
+                          - phone_number
+                        mask: true
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/imports/{_id}:
+    get:
+      x-internal: false
+      summary: Get a guardrail
+      description: |-
+        Returns the complete configuration of a specific guardrail import.
+        The `_id` is from the imports collection — the same ID used for any
+        import type.
+      operationId: getGuardrailById
+      tags:
+        - Guardrails
+      parameters:
+        - name: _id
+          in: path
+          description: The unique identifier of the guardrail import
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: imports
+            examples:
+              - 5f8d43a1b9e5a80011a35f2c
+      responses:
+        '200':
+          description: Guardrail retrieved successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Guardrail'
+              examples:
+                ai-agent-guardrail:
+                  summary: AI agent guardrail with BYOK
+                  value:
+                    _id: 69eb9f666fbf339ed3bc66c3
+                    createdAt: '2026-04-24T16:50:46.439Z'
+                    lastModified: '2026-04-24T16:50:53.525Z'
+                    name: Custom Validator
+                    _connectionId: 68ae48d6b5f755d2dd38c294
+                    apiIdentifier: i6a7acf995
+                    sandbox: false
+                    lookups: []
+                    adaptorType: GuardrailImport
+                    guardrail:
+                      type: ai_agent
+                      confidenceThreshold: 0.7
+                      aiAgent:
+                        provider: openai
+                        openai:
+                          instructions: Validate that each record has a non-empty email field.
+                          model: gpt-4.1-mini-2025-04-14
+                          tools: []
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Update a guardrail
+      description: |-
+        Replaces the guardrail import with the provided configuration.
+        This is a full replace -- include all fields you want to keep.
+        `adaptorType` must remain `GuardrailImport`.
+      operationId: updateGuardrail
+      tags:
+        - Guardrails
+      parameters:
+        - name: _id
+          in: path
+          description: The unique identifier of the guardrail import
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: imports
+            examples:
+              - 5f8d43a1b9e5a80011a35f2c
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              update-pii:
+                summary: Update PII guardrail to add masking
+                value:
+                  name: PII Scanner
+                  adaptorType: GuardrailImport
+                  guardrail:
+                    type: pii
+                    confidenceThreshold: 0.8
+                    pii:
+                      entities:
+                        - email_address
+                        - phone_number
+                        - credit_card_number
+                      mask: true
+      responses:
+        '200':
+          description: Guardrail updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Guardrail'
+              examples:
+                pii-updated:
+                  summary: PII guardrail after adding credit card masking
+                  value:
+                    _id: 69eb9f5078dbae2f1bb05f89
+                    createdAt: '2026-04-24T16:50:24.073Z'
+                    lastModified: '2026-05-02T16:12:08.114Z'
+                    name: PII Scanner
+                    apiIdentifier: i39ee734f7
+                    sandbox: false
+                    lookups: []
+                    adaptorType: GuardrailImport
+                    guardrail:
+                      type: pii
+                      confidenceThreshold: 0.8
+                      pii:
+                        entities:
+                          - email_address
+                          - phone_number
+                          - credit_card_number
+                        mask: true
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      summary: Delete a guardrail
+      description: |-
+        Deletes a guardrail import. Soft-deleted and retained in the recycle
+        bin for 30 days before permanent removal.
+      operationId: deleteGuardrail
+      tags:
+        - Guardrails
+      parameters:
+        - name: _id
+          in: path
+          description: The unique identifier of the guardrail import
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: imports
+            examples:
+              - 5f8d43a1b9e5a80011a35f2c
+      responses:
+        '204':
+          description: Guardrail deleted successfully
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-dependency-conflict'
+  /v1/imports/{_id}/dependencies:
+    get:
+      x-internal: false
+      operationId: listGuardrailDependencies
+      tags:
+        - Guardrails
+      summary: List dependencies of a guardrail
+      description: |-
+        Returns the set of resources that depend on the specified guardrail import.
+        The response is an object whose keys are dependent-resource types
+        (e.g. `flows`, `imports`) and whose values are arrays of dependency entries.
+
+        An empty object `{}` means no other resources depend on the target.
+        This is also returned for a well-formatted but nonexistent id.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Resource ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: imports
+            examples:
+              - 66a1f2c3b4d5e6f7a8b9c0d1
+      responses:
+        '200':
+          description: |
+            Dependency map. Keys are resource-type strings; values are arrays
+            of dependency entries. Returns `{}` when no dependents exist.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DependencyResponse'
+              examples:
+                none:
+                  summary: No dependents (also returned for a nonexistent ID)
+                  value: {}
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    Include:
+      name: include
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to project into each returned record.
+        Triggers summary projection: the response contains a minimal identity
+        set (`_id`, `name`, plus resource-specific fields) with the requested
+        fields added on top. Supports dot notation for nested fields.
+        Mutually exclusive with `exclude`.
+      schema:
+        type: string
+      example: _integrationId,disabled,lastModified
+    Exclude:
+      name: exclude
+      in: query
+      required: false
+      description: |-
+        Comma-separated list of fields to strip from the default response.
+        Unlike `include`, does not trigger summary projection — returns the
+        full record with the named fields removed. Protected identity fields
+        (e.g. `name`) cannot be stripped. Mutually exclusive with `include`.
+      schema:
+        type: string
+      example: createdAt,lastModified
+  schemas:
+    ResourceResponse:
+      type: object
+      description: Response
+      x-celigo-ai-guidance:
+        - Core response fields shared by all Celigo resources
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the resource. Format is a 24-character hexadecimal string.
+          x-celigo-ai-guidance:
+            - |-
+              The _id is used in:
+              - API endpoints that operate on a specific resource (e.g., GET, PUT, DELETE)
+              - References from other resources (e.g., flows that use this resource)
+              - Job history and error tracking
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was created. Set automatically and cannot be modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix).
+          examples:
+            - '2023-04-01T09:15:32Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was last updated. Changes whenever any property is modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+          examples:
+            - '2023-04-15T14:30:15Z'
+        deletedAt:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was soft-deleted. When null or absent, the resource is active.
+          x-celigo-ai-guidance:
+            - Non-null means the resource is soft-deleted (in the recycle bin) — recoverable within the retention period before permanent removal.
+          examples:
+            - '2023-05-20T11:45:32Z'
+      required:
+        - _id
+    IAResourceResponse:
+      type: object
+      description: Integration app response fields for resources that are part of integration apps
+      properties:
+        _integrationId:
+          type: string
+          format: objectId
+          x-celigo-refModel: integrations
+          readOnly: true
+          description: |
+            Reference to the specific integration instance that contains this resource.
+
+            This field is only populated for resources that are part of an integration app
+            installation. It contains the unique identifier (_id) of the integration
+            resource that was installed in the account.
+
+            The integration instance represents a specific installed instance of an
+            integration app, with its own configuration, settings, and runtime environment.
+
+            This reference enables:
+            - Tracing the resource back to its parent integration instance
+            - Permission and access control based on integration ownership
+            - Lifecycle management (enabling/disabling, updating, or uninstalling)
+          examples:
+            - 5f9a7b2c3d4e5f6a7b8c9d0e
+        _connectorId:
+          type: string
+          format: objectId
+          x-celigo-refModel: connectors
+          readOnly: true
+          description: |
+            Reference to the integration app that defines this resource.
+
+            This field is only populated for resources that are part of an integration app.
+            It contains the unique identifier (_id) of the integration app (connector)
+            that defines the structure, behavior, and templates for this resource.
+
+            The integration app is the published template that can be installed
+            multiple times across different accounts, with each installation creating
+            a separate integration instance (referenced by _integrationId).
+
+            This reference enables:
+            - Identifying the source integration app for this resource
+            - Determining which template version is being used
+            - Linking to documentation, support, and marketplace information
+          examples:
+            - 5e8d43a1b9e5a80011a35f1b
+          x-celigo-ai-guidance:
+            - |-
+              Read-only connector (Integration App template) reference; present only on
+              connector-owned resources. Never set or modify it when authoring resources.
+    McpResources:
+      type: array
+      description: |-
+        Governed MCP resources — read-only reference content (policies, schemas, documentation)
+        pulled from connected MCP servers and made available to the agent as a consistent source
+        of truth. Each entry references one MCP connection and the specific resources allowed from it.
+      items:
+        type: object
+        required:
+          - type
+          - mcp
+        properties:
+          type:
+            type: string
+            enum:
+              - mcp
+            x-enumDescriptions:
+              mcp: Reference read-only resources exposed by an MCP server.
+            description: Type of resource entry. Always "mcp".
+          mcp:
+            type: object
+            required:
+              - _mcpConnectionId
+              - allowedResources
+            description: MCP server resource configuration.
+            properties:
+              _mcpConnectionId:
+                type: string
+                format: objectId
+                x-celigo-refModel: connections
+                description: Connection to the MCP server that exposes the resources.
+              allowedResources:
+                type: array
+                minItems: 1
+                description: |-
+                  Resources to expose to the agent from the MCP server. Must contain at least one
+                  entry; each entry identifies one resource by name and URI.
+                items:
+                  type: object
+                  required:
+                    - name
+                    - uri
+                  properties:
+                    name:
+                      type: string
+                      description: Display name of the MCP resource.
+                      examples:
+                        - Data Retention Policy
+                    uri:
+                      type: string
+                      description: URI that identifies the resource on the MCP server.
+                      examples:
+                        - resource://policies/data-retention
+    AiAgentConfig:
+      type: object
+      description: |
+        AI Agent configuration used by both AiAgentImport and GuardrailImport (ai_agent type).
+
+        Configures which AI provider and model to use, along with instructions, parameter
+        tuning, output format, and available tools. Three providers are supported:
+
+        - **openai**: OpenAI models (GPT-4, GPT-4o, GPT-4o-mini, GPT-5, etc.). Configure via the `openai` object.
+        - **gemini**: Google Gemini models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.gemini`.
+        - **anthropic**: Anthropic Claude models via the LiteLLM proxy. Configure via `litellm` with overrides in `litellm._overrides.anthropic`.
+
+        A `_connectionId` is optional (BYOK). If not provided on the parent import,
+        platform-managed credentials are used.
+      required:
+        - provider
+      properties:
+        provider:
+          type: string
+          enum:
+            - openai
+            - gemini
+            - anthropic
+          x-enumDescriptions:
+            openai: Use OpenAI models via the OpenAI Responses API.
+            gemini: Use Google Gemini models via the LiteLLM proxy.
+            anthropic: Use Anthropic Claude models via the LiteLLM proxy.
+          description: AI provider to use.
+          x-celigo-ai-guidance:
+            - |-
+              - **openai**: Uses OpenAI Responses API. Configure via the `openai` object.
+              - **gemini**: Uses Google Gemini via LiteLLM. Configure via `litellm` with
+                Gemini-specific overrides in `litellm._overrides.gemini`.
+              - **anthropic**: Uses Anthropic Claude via LiteLLM. Configure via `litellm` with
+                Claude-specific overrides in `litellm._overrides.anthropic`.
+        openai:
+          type: object
+          description: |
+            OpenAI-specific configuration. Used when `provider` is "openai".
+          required:
+            - model
+            - instructions
+          properties:
+            instructions:
+              type: string
+              maxLength: 1000000
+              description: |
+                System prompt that defines the AI agent's behavior, goals, and constraints.
+              examples:
+                - You are a data validation agent. Check each record for completeness.
+              x-celigo-ui-override: Required by the AI agent configuration form (the model's system prompt). Encoded here to mirror the form so builders produce connectable configurations.
+            model:
+              type: string
+              description: OpenAI model identifier. Open string (not an enum) — model names change frequently.
+              examples:
+                - gpt-5.4
+                - gpt-5.4-pro
+                - gpt-5-mini
+                - gpt-5-nano
+                - gpt-4.1-mini
+                - gpt-4o
+              x-celigo-ui-override: Required by the AI agent configuration form. Encoded here to mirror the form so builders produce connectable configurations.
+              x-celigo-ai-guidance:
+                - |-
+                  With platform-managed credentials (no `_connectionId` on the parent
+                  import), the model must be on the platform's allowlist — an
+                  unlisted model fails the save with 422. A BYOK connection bypasses
+                  the allowlist and the model string is passed through to the
+                  provider as-is.
+            reasoning:
+              type: object
+              description: Controls depth of reasoning for complex tasks.
+              x-celigo-ai-guidance:
+                - |-
+                  Supported on reasoning-capable OpenAI models only (currently the GPT-5 family and the o-series).
+                  Setting `reasoning` on a non-reasoning model (e.g.
+                  `gpt-4.1-mini`) is rejected by the provider at runtime — omit the field on those models.
+              properties:
+                effort:
+                  type: string
+                  enum:
+                    - none
+                    - minimal
+                    - low
+                    - medium
+                    - high
+                    - xhigh
+                  x-enumDescriptions:
+                    none: No additional reasoning effort.
+                    minimal: Least reasoning effort for simple, straightforward tasks.
+                    low: Light reasoning for moderately simple tasks.
+                    medium: Balanced reasoning effort for typical tasks.
+                    high: Maximum reasoning effort for complex, multi-step tasks.
+                    xhigh: Highest reasoning effort for the most demanding, multi-step tasks.
+                  description: How much reasoning effort the model should invest
+                  x-celigo-ai-guidance:
+                    - |-
+                      How much reasoning effort the model should invest.
+                      Reasoning- capable models only — see `reasoning` for the gating rule.
+                summary:
+                  type: string
+                  enum:
+                    - concise
+                    - auto
+                    - detailed
+                  x-enumDescriptions:
+                    concise: Brief, high-level reasoning summary.
+                    auto: Let the model decide the appropriate level of detail.
+                    detailed: Comprehensive reasoning summary with full explanations.
+                  description: Level of detail in reasoning summaries
+                  x-celigo-ai-guidance:
+                    - |-
+                      Level of detail in reasoning summaries.
+                      Reasoning-capable models only — see `reasoning` for the gating rule.
+            temperature:
+              type: number
+              minimum: 0
+              maximum: 2
+              description: |
+                Sampling temperature. Higher values (e.g. 1.5) produce more creative output,
+                lower values (e.g. 0.2) produce more focused and deterministic output.
+            topP:
+              type: number
+              minimum: 0.1
+              maximum: 1
+              description: Nucleus sampling parameter
+            topLogprobs:
+              type: number
+              minimum: 0
+              maximum: 20
+              description: Number of most likely tokens to return log probabilities for at each output position.
+            maxOutputTokens:
+              type: number
+              minimum: 100
+              maximum: 128000
+              default: 5000
+              description: Maximum number of tokens in the model's response (server default observed live on create)
+            serviceTier:
+              type: string
+              enum:
+                - auto
+                - default
+                - priority
+              x-enumDescriptions:
+                auto: Let OpenAI automatically select the appropriate service tier.
+                default: Standard service tier with normal rate limits and latency.
+                priority: Premium tier with higher rate limits and lower latency at increased cost.
+              default: default
+              description: |-
+                OpenAI service tier. "priority" provides higher rate limits and
+                lower latency at increased cost.
+              x-celigo-ai-guidance:
+                - |-
+                  BYOK only.
+                  Platform-managed credentials (no `_connectionId` on the parent import) always
+                  run at `default` regardless of what's set here.
+            output:
+              type: object
+              description: Output format configuration
+              properties:
+                format:
+                  type: object
+                  description: |
+                    Controls the structure of the model's output.
+                  properties:
+                    type:
+                      type: string
+                      enum:
+                        - text
+                        - json_schema
+                        - blob
+                      x-enumDescriptions:
+                        text: Free-form text response from the model.
+                        json_schema: Structured JSON output conforming to a defined schema.
+                        blob: Binary data output for non-text content.
+                      default: text
+                      description: Output format type.
+                    schemaMode:
+                      type: string
+                      enum:
+                        - 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.
+                      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.
+                    name:
+                      type: string
+                      description: Name for the output format (used with json_schema)
+                      x-celigo-ui-override: Required by the AI agent form when output format type is json_schema. Encoded here to mirror the form so builders produce connectable configurations.
+                    strict:
+                      type: boolean
+                      default: false
+                      description: When true, enforces strict schema validation on output.
+                      x-celigo-ai-guidance:
+                        - Whether to enforce strict schema validation on output
+                    jsonSchema:
+                      type: object
+                      description: |
+                        JSON Schema for structured output. Required when `format.type` is "json_schema".
+                      x-celigo-ui-override: Required by the AI agent form when output format type is json_schema. Encoded here to mirror the form so builders produce connectable configurations.
+                      properties:
+                        type:
+                          type: string
+                          description: Root JSON Schema type of the structured output; use "object" for record-shaped results.
+                          enum:
+                            - object
+                            - array
+                            - string
+                            - number
+                            - integer
+                            - boolean
+                          x-enumDescriptions:
+                            object: JSON object with named properties.
+                            array: Ordered list of values.
+                            string: Text string value.
+                            number: Numeric value including decimals.
+                            integer: Whole number value without decimals.
+                            boolean: True or false value.
+                        properties:
+                          type: object
+                          additionalProperties: true
+                          description: JSON Schema definitions for each field the structured output may contain.
+                        required:
+                          type: array
+                          description: Property names the model must include in the structured output.
+                          items:
+                            type: string
+                        additionalproperties:
+                          type: boolean
+                          description: When true, the structured output may include properties beyond those defined in `properties`.
+                  if:
+                    properties:
+                      type:
+                        const: json_schema
+                    required:
+                      - type
+                  then:
+                    required:
+                      - name
+                      - jsonSchema
+                verbose:
+                  type: string
+                  enum:
+                    - low
+                    - medium
+                    - high
+                  x-enumDescriptions:
+                    low: Minimal detail in the model's response.
+                    medium: Moderate detail in the model's response, the default level.
+                    high: Maximum detail and verbosity in the model's response.
+                  default: medium
+                  description: Level of detail in the model's response
+                  x-celigo-ai-guidance:
+                    - |-
+                      Supported on the GPT-5 family only. Other OpenAI models (e.g.
+                      `gpt-4.1`, `gpt-4.1-mini`,
+                      `gpt-4.1-nano`) accept only `medium` (the no-op default) — `low` and `high` are
+                      rejected by the provider at runtime.
+                      Omit the field entirely on non-GPT-5 models rather than relying on the default.
+            tools:
+              type: array
+              description: |
+                Tools available to the AI agent during processing.
+              items:
+                type: object
+                properties:
+                  type:
+                    type: string
+                    enum:
+                      - web_search
+                      - mcp
+                      - image_generation
+                      - tool
+                    x-enumDescriptions:
+                      web_search: Search the web for real-time information.
+                      mcp: Connect to an MCP server for additional external tools.
+                      image_generation: Generate images using an AI image model.
+                      tool: Reference a reusable Celigo Tool resource.
+                    description: Type of tool.
+                  webSearch:
+                    type: object
+                    description: Web search configuration (empty object to enable)
+                  imageGeneration:
+                    type: object
+                    description: Image generation configuration
+                    properties:
+                      background:
+                        type: string
+                        description: Controls whether generated images have a transparent or opaque background; use transparent only with output formats that support it (png, webp).
+                        enum:
+                          - transparent
+                          - opaque
+                        x-enumDescriptions:
+                          transparent: Generate an image with a transparent background.
+                          opaque: Generate an image with a solid, non-transparent background.
+                      quality:
+                        type: string
+                        description: Rendering quality of generated images, trading detail for generation speed and file size.
+                        enum:
+                          - low
+                          - medium
+                          - high
+                        x-enumDescriptions:
+                          low: Lower quality for faster generation and smaller file size.
+                          medium: Balanced quality and generation speed.
+                          high: Highest quality output with more detail.
+                      size:
+                        type: string
+                        description: Pixel dimensions of generated images; choose square, portrait, or landscape to match the intended use.
+                        enum:
+                          - 1024x1024
+                          - 1024x1536
+                          - 1536x1024
+                        x-enumDescriptions:
+                          1024x1024: Square image at 1024 by 1024 pixels.
+                          1024x1536: Portrait image at 1024 by 1536 pixels.
+                          1536x1024: Landscape image at 1536 by 1024 pixels.
+                      outputFormat:
+                        type: string
+                        description: File format of generated images; use png or webp when transparency is needed.
+                        enum:
+                          - png
+                          - webp
+                          - jpeg
+                        x-enumDescriptions:
+                          png: PNG format with lossless compression, supports transparency.
+                          webp: WebP format with efficient compression for web use.
+                          jpeg: JPEG format with lossy compression for smaller file sizes.
+                  mcp:
+                    type: object
+                    description: MCP server tool configuration
+                    properties:
+                      _mcpConnectionId:
+                        type: string
+                        format: objectId
+                        x-celigo-refModel: connections
+                        description: Connection to the MCP server
+                      allowedTools:
+                        type: array
+                        description: |-
+                          Specific tools to allow from the MCP server (all if
+                          omitted). Each entry is either a plain tool name (legacy
+                          form) or an object carrying display metadata.
+                        items:
+                          type:
+                            - string
+                            - object
+                          properties:
+                            name:
+                              type: string
+                              maxLength: 256
+                              description: Tool name as exposed by the MCP server.
+                            title:
+                              type: string
+                              maxLength: 300
+                              description: Display title shown for the tool.
+                            description:
+                              type: string
+                              maxLength: 1000
+                              description: Display description shown for the tool.
+                          required:
+                            - name
+                          x-celigo-ai-guidance:
+                            - |-
+                              Object entries accept only name/title/description — any
+                              other key fails validation with "unknown field(s)", and
+                              an object without a non-empty name fails with a
+                              missing-required-field error. String entries are the
+                              legacy form and stay valid.
+                      allowedPrompts:
+                        type: array
+                        description: Specific prompts to allow from the MCP server (used for MCP prompt entries; all if omitted).
+                        items:
+                          type: string
+                  tool:
+                    type: object
+                    description: |
+                      Reference to a Celigo Tool resource.
+                    properties:
+                      _toolId:
+                        type: string
+                        format: objectId
+                        x-celigo-refModel: tools
+                        description: Reference to the Tool resource
+                      overrides:
+                        type: object
+                        description: Per-agent overrides for the tool's internal resources
+                        properties:
+                          connections:
+                            type: array
+                            description: |
+                              Remaps the tool's abstract connections for this agent. Each entry pairs
+                              the tool's abstract connection placeholder (`_abstractId`) with the
+                              concrete connection (`_id`) to use for this agent; entries without
+                              `_id` keep the tool's own default connection.
+                            items:
+                              type:
+                                - object
+                                - 'null'
+                              required:
+                                - _abstractId
+                              properties:
+                                _abstractId:
+                                  type: string
+                                  format: objectId
+                                  description: The tool's abstract connection placeholder being overridden.
+                                _id:
+                                  type: string
+                                  format: objectId
+                                  x-celigo-refModel: connections
+                                  description: Concrete connection to use in place of the abstract placeholder.
+            prompts:
+              type: array
+              description: |
+                MCP prompt entries available to the agent. Each item references one MCP connection
+                and the prompt names allowed from it. Configured alongside `tools` in the form but
+                stored separately; an entry's `allowedPrompts` is what distinguishes a prompt entry
+                from an MCP tool entry (which carries `allowedTools`).
+              items:
+                type: object
+                properties:
+                  type:
+                    type: string
+                    enum:
+                      - mcp
+                    x-enumDescriptions:
+                      mcp: Connect to an MCP server to use its exposed prompts.
+                    description: Type of prompt entry. Always "mcp".
+                  mcp:
+                    type: object
+                    description: MCP server prompt configuration.
+                    properties:
+                      _mcpConnectionId:
+                        type: string
+                        format: objectId
+                        x-celigo-refModel: connections
+                        description: Connection to the MCP server.
+                      allowedPrompts:
+                        type: array
+                        description: Prompt names to allow from the MCP server.
+                        items:
+                          type: string
+            resources:
+              $ref: '#/components/schemas/McpResources'
+        litellm:
+          type: object
+          description: |
+            LiteLLM proxy configuration. Used when `provider` is "gemini" or "anthropic".
+
+            LiteLLM provides a unified interface to multiple AI providers. Gemini-specific
+            settings are in `_overrides.gemini`; Claude-specific settings are in
+            `_overrides.anthropic`.
+
+            `model` is required when litellm is the active provider path.
+          properties:
+            model:
+              type: string
+              description: |-
+                LiteLLM model identifier. For Gemini, models are stored without the `gemini/`
+                prefix; for Anthropic, use the Claude model id (e.g. `claude-sonnet-4-6`).
+              examples:
+                - gemini-2.5-flash
+                - gemini-2.5-pro
+                - gemini-2.5-flash-lite
+                - claude-sonnet-4-6
+                - claude-opus-4-7
+              x-celigo-ui-override: Required by the AI agent configuration form. Encoded here to mirror the form so builders produce connectable configurations.
+            temperature:
+              type: number
+              minimum: 0
+              maximum: 2
+              description: Sampling temperature
+              x-celigo-ai-guidance:
+                - |-
+                  When `provider` is "anthropic", the value must be between 0 and 1 — a higher value
+                  fails the save with 422 `invalid_field_value`. Gemini accepts the full 0-2 range.
+            maxCompletionTokens:
+              type: number
+              minimum: 100
+              maximum: 128000
+              default: 5000
+              description: Maximum number of tokens in the response
+            topP:
+              type: number
+              minimum: 0.1
+              maximum: 1
+              description: Nucleus sampling parameter
+            seed:
+              type: number
+              description: Random seed for reproducible outputs
+            responseFormat:
+              type: object
+              description: Output format configuration
+              x-celigo-ai-guidance:
+                - |-
+                  When `provider` is "anthropic", `type` must be "text" or "json_schema" — "blob" is
+                  rejected with 422 `invalid_response_format`. As with the other providers, "json_schema"
+                  requires `name` and `jsonSchema`.
+              properties:
+                type:
+                  type: string
+                  description: Output format type.
+                  enum:
+                    - text
+                    - json_schema
+                    - blob
+                  x-enumDescriptions:
+                    text: Free-form text response from the model.
+                    json_schema: Structured JSON output conforming to a defined schema.
+                    blob: Binary data output for non-text content.
+                  default: text
+                schemaMode:
+                  type: string
+                  enum:
+                    - 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.
+                  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.
+                name:
+                  type: string
+                  description: Name for the output format (used with json_schema).
+                  x-celigo-ui-override: Required by the AI agent form when output format type is json_schema. Encoded here to mirror the form so builders produce connectable configurations.
+                strict:
+                  type: boolean
+                  description: When true, enforces strict schema validation on output.
+                  default: false
+                jsonSchema:
+                  type: object
+                  description: JSON Schema for structured output. Required when `responseFormat.type` is "json_schema".
+                  x-celigo-ui-override: Required by the AI agent form when output format type is json_schema. Encoded here to mirror the form so builders produce connectable configurations.
+                  properties:
+                    type:
+                      type: string
+                      description: Root JSON Schema type of the structured output; use "object" for record-shaped results.
+                      enum:
+                        - object
+                        - array
+                        - string
+                        - number
+                        - integer
+                        - boolean
+                      x-enumDescriptions:
+                        object: JSON object with named properties.
+                        array: Ordered list of values.
+                        string: Text string value.
+                        number: Numeric value including decimals.
+                        integer: Whole number value without decimals.
+                        boolean: True or false value.
+                    properties:
+                      type: object
+                      additionalProperties: true
+                      description: JSON Schema definitions for each field the structured output may contain.
+                    required:
+                      type: array
+                      description: Property names the model must include in the structured output.
+                      items:
+                        type: string
+                    additionalProperties:
+                      type: boolean
+                      description: When true, the structured output may include properties beyond those defined in `properties`.
+              if:
+                properties:
+                  type:
+                    const: json_schema
+                required:
+                  - type
+              then:
+                required:
+                  - name
+                  - jsonSchema
+            _overrides:
+              type: object
+              description: Provider-specific overrides
+              properties:
+                gemini:
+                  type: object
+                  description: |
+                    Gemini-specific configuration overrides.
+                  required:
+                    - systemInstruction
+                  properties:
+                    systemInstruction:
+                      type: string
+                      maxLength: 1000000
+                      description: |
+                        System instruction for Gemini models. Equivalent to OpenAI's `instructions`.
+                        Maximum 1,000,000 characters.
+                      x-celigo-ui-override: Required by the AI agent configuration form (the model's system prompt, the Gemini equivalent of `instructions`). Encoded here to mirror the form so builders produce connectable configurations.
+                    tools:
+                      type: array
+                      description: Gemini-specific tools
+                      items:
+                        type: object
+                        properties:
+                          type:
+                            type: string
+                            enum:
+                              - googleSearch
+                              - urlContext
+                              - fileSearch
+                              - mcp
+                              - tool
+                            x-enumDescriptions:
+                              googleSearch: Use Google Search for real-time information grounding.
+                              urlContext: Retrieve and use content from specified URLs.
+                              fileSearch: Search through previously uploaded files.
+                              mcp: Connect to an MCP server for additional external tools.
+                              tool: Reference a reusable Celigo Tool resource.
+                            description: Type of Gemini tool.
+                          googleSearch:
+                            type: object
+                            description: Google Search configuration (empty object to enable)
+                          urlContext:
+                            type: object
+                            description: URL context configuration (empty object to enable)
+                          fileSearch:
+                            type: object
+                            description: File search configuration, used when type is "fileSearch".
+                            properties:
+                              fileSearchStoreNames:
+                                type: array
+                                description: Names of the file search stores the model can query.
+                                items:
+                                  type: string
+                          mcp:
+                            type: object
+                            description: MCP server tool configuration, used when type is "mcp".
+                            properties:
+                              _mcpConnectionId:
+                                type: string
+                                format: objectId
+                                x-celigo-refModel: connections
+                                description: Connection to the MCP server.
+                              allowedTools:
+                                type: array
+                                description: |-
+                                  Specific tools to allow from the MCP server (all if
+                                  omitted). Each entry is either a plain tool name
+                                  (legacy form) or an object carrying display metadata
+                                  — same contract as the OpenAI `allowedTools`.
+                                items:
+                                  type:
+                                    - string
+                                    - object
+                                  properties:
+                                    name:
+                                      type: string
+                                      maxLength: 256
+                                      description: Tool name as exposed by the MCP server.
+                                    title:
+                                      type: string
+                                      maxLength: 300
+                                      description: Display title shown for the tool.
+                                    description:
+                                      type: string
+                                      maxLength: 1000
+                                      description: Display description shown for the tool.
+                                  required:
+                                    - name
+                              allowedPrompts:
+                                type: array
+                                description: Specific prompts to allow from the MCP server (used for MCP prompt entries; all if omitted).
+                                items:
+                                  type: string
+                          tool:
+                            type: object
+                            description: Reference to a Celigo Tool resource, used when type is "tool".
+                            properties:
+                              _toolId:
+                                type: string
+                                format: objectId
+                                x-celigo-refModel: tools
+                                description: Reference to the Tool resource.
+                              overrides:
+                                type: object
+                                description: Per-agent overrides for the tool's internal resources.
+                                properties:
+                                  connections:
+                                    type: array
+                                    description: |
+                                      Remaps the tool's abstract connections for this agent. Each entry
+                                      pairs the tool's abstract connection placeholder (`_abstractId`)
+                                      with the concrete connection (`_id`) to use for this agent;
+                                      entries without `_id` keep the tool's own default connection.
+                                    items:
+                                      type:
+                                        - object
+                                        - 'null'
+                                      required:
+                                        - _abstractId
+                                      properties:
+                                        _abstractId:
+                                          type: string
+                                          format: objectId
+                                          description: The tool's abstract connection placeholder being overridden.
+                                        _id:
+                                          type: string
+                                          format: objectId
+                                          x-celigo-refModel: connections
+                                          description: Concrete connection to use in place of the abstract placeholder.
+                    prompts:
+                      type: array
+                      description: |
+                        MCP prompt entries available to the Gemini agent. Each item references one
+                        MCP connection and the prompt names allowed from it. The presence of
+                        `allowedPrompts` distinguishes a prompt entry from an MCP tool entry.
+                      items:
+                        type: object
+                        properties:
+                          type:
+                            type: string
+                            enum:
+                              - mcp
+                            x-enumDescriptions:
+                              mcp: Connect to an MCP server to use its exposed prompts.
+                            description: Type of prompt entry. Always "mcp".
+                          mcp:
+                            type: object
+                            description: MCP server prompt configuration.
+                            properties:
+                              _mcpConnectionId:
+                                type: string
+                                format: objectId
+                                x-celigo-refModel: connections
+                                description: Connection to the MCP server.
+                              allowedPrompts:
+                                type: array
+                                description: Prompt names to allow from the MCP server.
+                                items:
+                                  type: string
+                    resources:
+                      $ref: '#/components/schemas/McpResources'
+                    responseModalities:
+                      type: array
+                      description: Response output modalities
+                      x-celigo-ai-guidance:
+                        - |-
+                          `["image"]` requires an image-capable Gemini model (currently `gemini-2.5-flash-image`).
+                          Selecting it on a text-only model is rejected by the provider — pair image
+                          output with the right model or omit.
+                      items:
+                        type: string
+                        enum:
+                          - text
+                          - image
+                        x-enumDescriptions:
+                          text: Generate text content in the response.
+                          image: Generate image content in the response.
+                      default:
+                        - text
+                    topK:
+                      type: number
+                      description: Top-K sampling parameter for Gemini
+                    thinkingConfig:
+                      type: object
+                      description: Controls Gemini's extended thinking capabilities
+                      x-celigo-ai-guidance:
+                        - |-
+                          Supported on reasoning-capable Gemini models only (currently `gemini-2.5-pro`
+                          and `gemini-2.5-flash`).
+                          Setting `thinkingConfig` on a non-thinking model (e.g.
+                          `gemini-2.5-flash-lite`,
+                          `gemini-2.5-flash-image`) is rejected by the provider at runtime — omit the
+                          field on those models.
+                      properties:
+                        includeThoughts:
+                          type: boolean
+                          description: When true, includes the model's thinking steps in the response.
+                          x-celigo-ai-guidance:
+                            - Whether to include thinking steps in the response
+                        thinkingBudget:
+                          type: number
+                          minimum: 100
+                          maximum: 4000
+                          description: Maximum tokens allocated for thinking
+                        thinkingLevel:
+                          type: string
+                          description: Controls how much thinking effort the model applies; use higher levels for complex, multi-step tasks at the cost of latency and tokens.
+                          enum:
+                            - minimal
+                            - low
+                            - medium
+                            - high
+                          x-enumDescriptions:
+                            minimal: Least thinking effort for simple tasks.
+                            low: Light thinking for moderately simple tasks.
+                            medium: Balanced thinking effort for typical tasks.
+                            high: Maximum thinking effort for complex, multi-step tasks.
+                    imageConfig:
+                      type: object
+                      description: Gemini image generation configuration
+                      properties:
+                        aspectRatio:
+                          type: string
+                          description: Aspect ratio of generated images; choose a ratio matching the intended display format.
+                          enum:
+                            - '1:1'
+                            - '2:3'
+                            - '3:2'
+                            - '3:4'
+                            - '4:3'
+                            - '4:5'
+                            - '5:4'
+                            - '9:16'
+                            - '16:9'
+                            - '21:9'
+                          x-enumDescriptions:
+                            '1:1': Square aspect ratio.
+                            '2:3': Portrait aspect ratio (2 wide by 3 tall).
+                            '3:2': Landscape aspect ratio (3 wide by 2 tall).
+                            '3:4': Portrait aspect ratio (3 wide by 4 tall).
+                            '4:3': Standard landscape aspect ratio (4 wide by 3 tall).
+                            '4:5': Portrait aspect ratio (4 wide by 5 tall).
+                            '5:4': Landscape aspect ratio (5 wide by 4 tall).
+                            '9:16': Tall portrait aspect ratio for mobile screens.
+                            '16:9': Widescreen landscape aspect ratio.
+                            '21:9': Ultra-widescreen cinematic aspect ratio.
+                        imageSize:
+                          type: string
+                          description: Output resolution of generated images; higher resolutions increase detail and file size.
+                          enum:
+                            - 1K
+                            - 2K
+                            - 4K
+                          x-enumDescriptions:
+                            1K: Standard resolution output around 1024 pixels.
+                            2K: High resolution output around 2048 pixels.
+                            4K: Ultra-high resolution output around 4096 pixels.
+                    mediaResolution:
+                      type: string
+                      enum:
+                        - low
+                        - medium
+                        - high
+                      x-enumDescriptions:
+                        low: Low resolution for faster processing and reduced token usage.
+                        medium: Balanced resolution for typical media processing.
+                        high: High resolution for maximum detail in media inputs.
+                      description: Resolution for media inputs (images, video)
+                anthropic:
+                  type: object
+                  description: |
+                    Claude-specific configuration overrides. Used when `provider` is "anthropic".
+                  required:
+                    - systemInstruction
+                  properties:
+                    systemInstruction:
+                      type: string
+                      maxLength: 1000000
+                      description: |
+                        System instruction for Claude models. Equivalent to OpenAI's `instructions`.
+                        Maximum 1,000,000 characters.
+                      x-celigo-ui-override: Required by the AI agent configuration form (the model's system prompt, the Claude equivalent of `instructions`). Encoded here to mirror the form so builders produce connectable configurations.
+                    topK:
+                      type: number
+                      minimum: 0
+                      description: |-
+                        Top-K sampling parameter. Deprecated on Claude models released after Claude Opus
+                        4.6, which reject any value at runtime; set it only on older models.
+                    thinkingConfig:
+                      type: object
+                      description: Controls Claude's extended thinking capabilities.
+                      properties:
+                        type:
+                          type: string
+                          enum:
+                            - enabled
+                            - disabled
+                            - adaptive
+                          x-enumDescriptions:
+                            enabled: Turn on extended thinking with an explicit token budget.
+                            disabled: Turn off extended thinking.
+                            adaptive: Let the model decide how much to think based on task complexity.
+                          default: disabled
+                          description: Extended thinking mode.
+                        budgetTokens:
+                          type: number
+                          minimum: 1024
+                          description: |-
+                            Maximum tokens allocated for thinking. Required when `type` is "enabled" —
+                            omitting it fails the save with 422 `invalid_thinking_config`.
+                          x-celigo-ui-override: Required by the AI agent form when thinkingConfig.type is "enabled". Encoded here to mirror the form so builders produce connectable configurations.
+                        display:
+                          type: string
+                          enum:
+                            - summarized
+                            - omitted
+                          x-enumDescriptions:
+                            summarized: Include a summarized view of the model's thinking in the response.
+                            omitted: Exclude the model's thinking from the response.
+                          default: summarized
+                          description: How thinking output is surfaced in the response.
+                        effort:
+                          type: string
+                          enum:
+                            - low
+                            - medium
+                            - high
+                            - xhigh
+                            - max
+                          x-enumDescriptions:
+                            low: Light thinking effort for moderately simple tasks.
+                            medium: Balanced thinking effort for typical tasks.
+                            high: Maximum standard thinking effort for complex tasks.
+                            xhigh: Extended thinking effort beyond high for demanding tasks.
+                            max: Highest available thinking effort.
+                          description: |-
+                            How much thinking effort the model applies; use with `type` "adaptive". Higher
+                            values (`xhigh`, `max`) may be gated to specific Claude models by the provider.
+                      if:
+                        properties:
+                          type:
+                            const: enabled
+                        required:
+                          - type
+                      then:
+                        required:
+                          - budgetTokens
+                    serviceTier:
+                      type: string
+                      enum:
+                        - auto
+                        - standard_only
+                      x-enumDescriptions:
+                        auto: Let Anthropic select the appropriate service tier.
+                        standard_only: Restrict processing to the standard service tier.
+                      default: auto
+                      description: Anthropic service tier for the request.
+                    tools:
+                      type: array
+                      description: Claude-specific tools.
+                      items:
+                        type: object
+                        properties:
+                          type:
+                            type: string
+                            enum:
+                              - tool
+                              - mcp
+                              - webSearch
+                            x-enumDescriptions:
+                              tool: Reference a reusable Celigo Tool resource.
+                              mcp: Connect to an MCP server for additional external tools.
+                              webSearch: Search the web for real-time information.
+                            description: Type of Claude tool.
+                          tool:
+                            type: object
+                            description: Reference to a Celigo Tool resource, used when type is "tool".
+                            properties:
+                              _toolId:
+                                type: string
+                                format: objectId
+                                x-celigo-refModel: tools
+                                description: Reference to the Tool resource.
+                              overrides:
+                                type: object
+                                description: Per-agent overrides for the tool's internal resources.
+                                properties:
+                                  connections:
+                                    type: array
+                                    description: |
+                                      Remaps the tool's abstract connections for this agent. Each entry
+                                      pairs the tool's abstract connection placeholder (`_abstractId`)
+                                      with the concrete connection (`_id`) to use for this agent;
+                                      entries without `_id` keep the tool's own default connection.
+                                    items:
+                                      type:
+                                        - object
+                                        - 'null'
+                                      required:
+                                        - _abstractId
+                                      properties:
+                                        _abstractId:
+                                          type: string
+                                          format: objectId
+                                          description: The tool's abstract connection placeholder being overridden.
+                                        _id:
+                                          type: string
+                                          format: objectId
+                                          x-celigo-refModel: connections
+                                          description: Concrete connection to use in place of the abstract placeholder.
+                          mcp:
+                            type: object
+                            description: MCP server tool configuration, used when type is "mcp".
+                            properties:
+                              _mcpConnectionId:
+                                type: string
+                                format: objectId
+                                x-celigo-refModel: connections
+                                description: Connection to the MCP server.
+                              allowedTools:
+                                type: array
+                                description: Specific tools to allow from the MCP server (all if omitted).
+                                items:
+                                  type: string
+                          webSearch:
+                            type: object
+                            description: Web search configuration, used when type is "webSearch".
+                            x-celigo-ai-guidance:
+                              - |-
+                                `allowedDomains` and `blockedDomains` are mutually exclusive — set at most
+                                one. Sending both fails with 422 `invalid_hosted_tool`.
+                              - |-
+                                When `userLocation` is present, set at least one of `city`, `country`,
+                                `region`, or `timezone`; an empty `userLocation` fails with 422
+                                `missing_required_field`.
+                            properties:
+                              version:
+                                type: string
+                                pattern: ^\d{8}$
+                                description: |-
+                                  Anthropic web search tool version (YYYYMMDD). Selects the tool version sent
+                                  on the wire; unsupported versions surface as an Anthropic 400.
+                                examples:
+                                  - '20250305'
+                              allowedDomains:
+                                type: array
+                                description: Domains the search may return results from. Mutually exclusive with `blockedDomains`.
+                                items:
+                                  type: string
+                              blockedDomains:
+                                type: array
+                                description: Domains to exclude from search results. Mutually exclusive with `allowedDomains`.
+                                items:
+                                  type: string
+                              userLocation:
+                                type: object
+                                description: |-
+                                  Approximate user location used to localize search results. When present, at
+                                  least one of `city`, `country`, `region`, or `timezone` must be set.
+                                properties:
+                                  type:
+                                    type: string
+                                    enum:
+                                      - approximate
+                                    x-enumDescriptions:
+                                      approximate: Localize results to an approximate user location.
+                                    description: Location type. Always "approximate".
+                                  city:
+                                    type: string
+                                    maxLength: 256
+                                    description: City name for localizing search results.
+                                  country:
+                                    type: string
+                                    maxLength: 8
+                                    description: ISO 3166-1 alpha-2 country code for localizing search results.
+                                  region:
+                                    type: string
+                                    maxLength: 256
+                                    description: Region or state for localizing search results.
+                                  timezone:
+                                    type: string
+                                    maxLength: 64
+                                    description: IANA timezone for localizing search results.
+                    prompts:
+                      type: array
+                      description: |
+                        MCP prompt entries available to the Claude agent. Each item references one MCP
+                        connection and the prompt names allowed from it. The presence of `allowedPrompts`
+                        distinguishes a prompt entry from an MCP tool entry.
+                      items:
+                        type: object
+                        properties:
+                          type:
+                            type: string
+                            enum:
+                              - mcp
+                            x-enumDescriptions:
+                              mcp: Connect to an MCP server to use its exposed prompts.
+                            description: Type of prompt entry. Always "mcp".
+                          mcp:
+                            type: object
+                            description: MCP server prompt configuration.
+                            properties:
+                              _mcpConnectionId:
+                                type: string
+                                format: objectId
+                                x-celigo-refModel: connections
+                                description: Connection to the MCP server.
+                              allowedPrompts:
+                                type: array
+                                description: Prompt names to allow from the MCP server.
+                                items:
+                                  type: string
+                    resources:
+                      $ref: '#/components/schemas/McpResources'
+      if:
+        properties:
+          provider:
+            const: openai
+        required:
+          - provider
+      then:
+        required:
+          - openai
+        properties:
+          openai:
+            required:
+              - model
+              - instructions
+      else:
+        if:
+          properties:
+            provider:
+              enum:
+                - gemini
+                - anthropic
+          required:
+            - provider
+        then:
+          required:
+            - litellm
+          properties:
+            litellm:
+              required:
+                - model
+    GuardrailConfig:
+      type: object
+      description: |-
+        Configuration for GuardrailImport adaptor type.
+
+        Guardrails evaluate data flowing through integrations for safety and
+        compliance. The `type` field selects which check to apply, and the
+        corresponding sub-object (`aiAgent`, `pii`, or `moderation`) provides
+        the configuration.
+
+        A `_connectionId` on the parent import is only needed for BYOK
+        `ai_agent` guardrails. In responses the server echoes the active type's
+        sub-object and applies the `confidenceThreshold` default; it also
+        returns inactive sibling sub-objects (e.g. `moderation: {categories: []}`
+        on a `pii` guardrail, or a populated `pii` left over from a type switch),
+        but only the active type's sub-object is meaningful. Legacy documents
+        may carry a server-written default `aiAgent` stub on `pii`/`moderation`
+        guardrails; current servers strip the inactive `aiAgent` on write.
+      x-celigo-ai-guidance:
+        - |-
+          Guardrails are safety and compliance checks that can be applied
+          to data flowing through integrations.  Three mutually-exclusive
+          types are supported — see `type` below for the full decision
+          rule on which to pick:
+
+          - **pii**: Detect (and optionally mask) personally identifiable
+            information.  Local deterministic classifier; fixed enum of
+            entity types (`pii.entities`).
+          - **moderation**: Detect harmful / inappropriate / policy-
+            violating CONTENT.  Local deterministic classifier; fixed enum
+            of categories (`moderation.categories` — `sexual`, `hate`,
+            `harassment`, `self_harm`, `violence`, `illicit`, etc.).  Use
+            category names exactly as listed in the enum — e.g. `hate`
+            (not "hate speech"), `violence` (not "violent content").  Map
+            natural-language synonyms ("explicit" → `sexual`, "toxic" →
+            `harassment`, etc.) to the closest enum value rather than
+            falling back to `ai_agent`.
+          - **ai_agent**: LLM-evaluated judgement against custom
+            instructions.  Catch-all for intents that don't fit `pii` or
+            `moderation` — domain-specific compliance, business-policy
+            checks, data-quality assertions, etc.  Pick this LAST, not as
+            the default.
+        - |-
+          Prefer the cheaper / more deterministic types (`pii` > `moderation` >
+          `ai_agent`) whenever the brief's intent fits.
+        - Guardrail imports do not require a `_connectionId` (unless using BYOK for `ai_agent` type).
+      properties:
+        type:
+          type: string
+          enum:
+            - ai_agent
+            - pii
+            - moderation
+          x-enumDescriptions:
+            ai_agent: Evaluate data using an AI model with custom instructions.
+            pii: Detect personally identifiable information in data fields.
+            moderation: Check content for harmful or inappropriate categories.
+          description: |-
+            The type of guardrail to apply. Each type requires its corresponding
+            sub-configuration object (`aiAgent`, `pii`, or `moderation`).
+          x-celigo-ai-guidance:
+            - |-
+              The type of guardrail to apply.
+              Pick exactly one — `pii` / `moderation` / `ai_agent` are mutually exclusive at
+              the type level (a brief that wants both runs as two guardrails in sequence,
+              not one).
+            - |-
+              ## How to choose
+
+              Apply these rules **in order** and pick the first match.  Do
+              NOT skip ahead to `ai_agent` just because the brief is in
+              natural language — `pii` and `moderation` are also expressed
+              as natural-language briefs.  The decision is about WHAT the
+              brief asks the guardrail to detect, not how the brief is
+              worded.
+
+              1. **`pii`** — pick this when the brief names ANY personally
+                 identifiable information, OR when the brief names entity
+                 categories (SSN, email, phone, credit card, address, name,
+                 passport, license, account number, etc.) that match
+                 `pii.entities`.  Examples that route here:
+                 "detect SSN and credit card numbers", "mask customer
+                 emails and phone numbers", "scan for PII".
+
+              2. **`moderation`** — pick this when the brief asks the
+                 guardrail to detect harmful, inappropriate, unsafe, or
+                 policy-violating CONTENT (as opposed to PII data fields)
+                 AND the intent maps to any value in `moderation.categories`
+                 (`sexual`, `hate`, `harassment`, `self_harm`, `violence`,
+                 `illicit`, etc.) — including via close synonyms.  Apply
+                 the synonym mapping liberally:
+                 - "explicit", "obscene", "vulgar", "profane",
+                   "inappropriate language", "swearing", "NSFW" → typically
+                   maps to `sexual` and/or `harassment`
+                 - "abusive", "insulting", "bullying", "toxic" → `harassment`
+                 - "hateful", "discriminatory", "racist", "sexist" → `hate`
+                 - "threatening", "intimidating" → `harassment_threatening`
+                   or `violence`
+                 - "graphic violence", "gore" → `violence_graphic`
+                 - "suicide", "self-injury" → `self_harm`
+                 - "drugs", "weapons", "illegal activity" → `illicit`
+                 Briefs like "screen email body for explicit language",
+                 "block toxic chat messages", "flag harassment in support
+                 tickets", "moderate user-generated content for unsafe
+                 material" all route to `moderation`.  When the brief uses
+                 a synonym, populate `moderation.categories` with the
+                 closest enum value(s) — do NOT invent new category
+                 strings; the enum is fixed.
+
+              3. **`ai_agent`** — pick this ONLY when the brief asks for
+                 judgement that doesn't fit `pii` or `moderation`.  Typical
+                 triggers: domain-specific compliance checks (HIPAA / SOX
+                 rule evaluation), business-policy validation (price
+                 bounds, approval thresholds), data-quality assertions
+                 (required fields populated, values plausible), or any
+                 "evaluate against these custom rules" framing where the
+                 rules are domain-specific and have no `pii.entities` /
+                 `moderation.categories` analogue.  If you can map the
+                 brief's intent to a moderation category (even via a
+                 synonym above), use `moderation` instead — `ai_agent` is
+                 the catch-all, not the default.
+
+              Tie-breaker for borderline cases: prefer the more specific
+              type (`pii` > `moderation` > `ai_agent`).  `pii` and
+              `moderation` are local deterministic classifiers with fixed
+              enums — they're cheaper, faster, and more predictable than
+              `ai_agent` (which calls a real LLM per record).  Default to
+              the cheaper path whenever the intent fits.
+            - |-
+              ## Sub-configuration requirements (one per type)
+
+              - **ai_agent** requires the `aiAgent` sub-configuration.
+              - **pii** requires the `pii` sub-configuration with at least
+                one entity from `pii.entities`.
+              - **moderation** requires the `moderation` sub-configuration
+                with at least one category from `moderation.categories`.
+        confidenceThreshold:
+          type: number
+          minimum: 0
+          maximum: 1
+          default: 0.7
+          x-celigo-ui-override: Required by the guardrail form (confidenceThreshold is required:true once a type is selected, default 0.7). Encoded to mirror the form so builders produce connectable configurations.
+          description: |-
+            Confidence threshold (0 to 1). Detections below this threshold are
+            ignored. Lower values catch more issues but increase false positives.
+          x-celigo-ai-guidance:
+            - Confidence threshold for guardrail detection (0 to 1).
+            - |-
+              Only detections with confidence at or above this threshold will be flagged.
+              Lower values catch more potential issues but may increase false positives.
+          examples:
+            - 0.7
+            - 0.5
+            - 0.9
+        aiAgent:
+          type: object
+          description: |-
+            AI agent check configuration; set when `type` is `ai_agent`. On
+            `pii`/`moderation` guardrails a legacy server-written stub may
+            appear here — it is inert, and current servers strip it on write.
+        pii:
+          type: object
+          required:
+            - entities
+          description: PII detection configuration. Required when `type` is `pii`.
+          x-celigo-ai-guidance:
+            - Configuration for PII (Personally Identifiable Information) detection.
+            - |-
+              Required when `guardrail.type` is "pii".
+              At least one entity type must be specified.
+          properties:
+            entities:
+              type: array
+              description: |-
+                PII entity types to detect. When `type` is `pii`, at least one
+                entry is required; the inactive sibling on other guardrail types
+                may be served with an empty list.
+              x-celigo-ai-guidance:
+                - PII entity types to detect in the data.
+                - At least one entity must be specified when using PII guardrails.
+              items:
+                type: string
+                enum:
+                  - credit_card_number
+                  - card_security_code_cvv_cvc
+                  - cryptocurrency_wallet_address
+                  - date_and_time
+                  - email_address
+                  - iban_code
+                  - bic_swift_bank_identifier_code
+                  - ip_address
+                  - location
+                  - medical_license_number
+                  - national_registration_number
+                  - persons_name
+                  - phone_number
+                  - url
+                  - us_bank_account_number
+                  - us_drivers_license
+                  - us_itin
+                  - us_passport_number
+                  - us_social_security_number
+                  - uk_nhs_number
+                  - uk_national_insurance_number
+                  - spanish_nif
+                  - spanish_nie
+                  - italian_fiscal_code
+                  - italian_drivers_license
+                  - italian_vat_code
+                  - italian_passport
+                  - italian_identity_card
+                  - polish_pesel
+                  - finnish_personal_identity_code
+                  - singapore_nric_fin
+                  - singapore_uen
+                  - australian_abn
+                  - australian_acn
+                  - australian_tfn
+                  - australian_medicare
+                  - indian_pan
+                  - indian_aadhaar
+                  - indian_vehicle_registration
+                  - indian_voter_id
+                  - indian_passport
+                  - korean_resident_registration_number
+                x-enumDescriptions:
+                  credit_card_number: Credit or debit card number (e.g., Visa, Mastercard, Amex).
+                  card_security_code_cvv_cvc: Card security code printed on credit or debit cards (CVV/CVC).
+                  cryptocurrency_wallet_address: Cryptocurrency wallet address (e.g., Bitcoin, Ethereum).
+                  date_and_time: Date and/or time values that could identify an individual.
+                  email_address: Email address in standard format.
+                  iban_code: International Bank Account Number used for cross-border payments.
+                  bic_swift_bank_identifier_code: BIC/SWIFT code identifying a specific bank for international transfers.
+                  ip_address: IPv4 or IPv6 network address.
+                  location: Physical location or geographic coordinates.
+                  medical_license_number: Medical professional license or registration number.
+                  national_registration_number: National identification or registration number.
+                  persons_name: Full or partial name of a person.
+                  phone_number: Telephone number in any format.
+                  url: Web URL or URI.
+                  us_bank_account_number: United States bank account number.
+                  us_drivers_license: United States driver's license number.
+                  us_itin: United States Individual Taxpayer Identification Number.
+                  us_passport_number: United States passport number.
+                  us_social_security_number: United States Social Security Number (SSN).
+                  uk_nhs_number: United Kingdom National Health Service number.
+                  uk_national_insurance_number: United Kingdom National Insurance number.
+                  spanish_nif: Spanish tax identification number (NIF).
+                  spanish_nie: Spanish foreigner identification number (NIE).
+                  italian_fiscal_code: Italian fiscal code (Codice Fiscale).
+                  italian_drivers_license: Italian driver's license number.
+                  italian_vat_code: Italian VAT identification number (Partita IVA).
+                  italian_passport: Italian passport number.
+                  italian_identity_card: Italian national identity card number.
+                  polish_pesel: Polish national identification number (PESEL).
+                  finnish_personal_identity_code: Finnish personal identity code (henkilotunnus).
+                  singapore_nric_fin: Singapore National Registration Identity Card or Foreign Identification Number.
+                  singapore_uen: Singapore Unique Entity Number for business registration.
+                  australian_abn: Australian Business Number.
+                  australian_acn: Australian Company Number.
+                  australian_tfn: Australian Tax File Number.
+                  australian_medicare: Australian Medicare card number.
+                  indian_pan: Indian Permanent Account Number for tax purposes.
+                  indian_aadhaar: Indian Aadhaar unique identity number.
+                  indian_vehicle_registration: Indian vehicle registration number.
+                  indian_voter_id: Indian voter identification card number.
+                  indian_passport: Indian passport number.
+                  korean_resident_registration_number: South Korean resident registration number.
+              examples:
+                - - email_address
+                  - phone_number
+                  - persons_name
+                - - us_social_security_number
+                  - credit_card_number
+            mask:
+              type: boolean
+              default: false
+              description: |-
+                When true, detected PII is replaced with masked values.
+                When false, PII is flagged without modification.
+              x-celigo-ai-guidance:
+                - Whether to mask detected PII values in the output.
+        moderation:
+          type: object
+          required:
+            - categories
+          description: Content moderation configuration. Required when `type` is `moderation`.
+          x-celigo-ai-guidance:
+            - |-
+              Required when `guardrail.type` is "moderation".
+              At least one category must be specified.
+          properties:
+            categories:
+              type: array
+              description: |-
+                Content moderation categories to check. When `type` is
+                `moderation`, at least one entry is required; the inactive
+                sibling on other guardrail types may be served with an empty
+                list.
+              x-celigo-ai-guidance:
+                - At least one category must be specified when using moderation guardrails.
+              items:
+                type: string
+                enum:
+                  - sexual
+                  - sexual_minors
+                  - hate
+                  - hate_threatening
+                  - harassment
+                  - harassment_threatening
+                  - self_harm
+                  - self_harm_intent
+                  - self_harm_instructions
+                  - violence
+                  - violence_graphic
+                  - illicit
+                  - illicit_violent
+                x-enumDescriptions:
+                  sexual: Content depicting sexual activity or explicit sexual material.
+                  sexual_minors: Sexual content involving minors.
+                  hate: Content expressing hatred toward a group based on protected characteristics.
+                  hate_threatening: Hateful content that includes threats of violence or serious harm.
+                  harassment: Content that targets, intimidates, or bullies an individual.
+                  harassment_threatening: Harassment content that includes threats of violence or serious harm.
+                  self_harm: Content that promotes or depicts self-harm behaviors.
+                  self_harm_intent: Content expressing intent to engage in self-harm.
+                  self_harm_instructions: Content providing instructions for self-harm methods.
+                  violence: Content depicting or promoting physical violence.
+                  violence_graphic: Graphic or gory depictions of violence or injury.
+                  illicit: Content promoting illegal activities or unlawful behavior.
+                  illicit_violent: Content promoting illegal activities that involve violence.
+              examples:
+                - - hate
+                  - violence
+                  - harassment
+                - - sexual
+                  - self_harm
+                  - illicit
+      required:
+        - type
+        - confidenceThreshold
+      if:
+        required:
+          - type
+        properties:
+          type:
+            const: pii
+      then:
+        required:
+          - pii
+        properties:
+          pii:
+            required:
+              - entities
+            properties:
+              entities:
+                minItems: 1
+      else:
+        if:
+          required:
+            - type
+          properties:
+            type:
+              const: moderation
+        then:
+          required:
+            - moderation
+          properties:
+            moderation:
+              required:
+                - categories
+              properties:
+                categories:
+                  minItems: 1
+        else:
+          required:
+            - aiAgent
+          properties:
+            aiAgent:
+              $ref: '#/components/schemas/AiAgentConfig'
+    MappingField:
+      type: object
+      description: One Mapper 1.0 field-mapping entry.
+      properties:
+        generate:
+          type: string
+          description: Target field path to write on the destination record.
+          examples:
+            - billingAddress.city
+          x-celigo-ai-guidance:
+            - |-
+              Destination field path on the target record. Use the target
+              system's raw field id — for Salesforce the API name (e.g.
+              ``AccountId``, ``CustomField__c``); for HTTP/REST the JSON
+              key the endpoint expects; for NetSuite the internal field id
+              (lowercase, no spaces).
+
+              Mapper 1.0 expands two notations into the destination
+              structure at write time:
+
+              - **Dot notation** — ``customer.email`` builds nested
+                objects, writing ``{customer: {email: value}}``. Use it
+                freely for any depth of nested object on adaptors whose
+                payloads are JSON (HTTP, REST, Shopify-style, etc.).
+                NetSuite body fields are flat — do not use dot notation
+                there.
+              - **Bracket-star notation** — ``addresses[*].company`` is the
+                idiomatic V1 expression for "this scalar belongs to every
+                element of the destination array as it is being
+                constructed." Two or more ``[*]``-suffixed fields with the
+                same array prefix collaborate to populate a single element
+                per source record, e.g. pairing
+                ``customer.addresses[*].company`` with
+                ``customer.addresses[*].city`` produces one address object
+                carrying both fields.
+              - **Numeric bracket notation** — ``addresses[0].company``
+                writes to a specific index. It works, but hardcodes the
+                slot and is only appropriate when the destination genuinely
+                targets a fixed position (rare). Prefer ``[*]`` whenever
+                the user describes "an address" / "a line" / "an entry";
+                reserve ``[N]`` for "the second address" and similar
+                explicit-index intents.
+
+              customer.email                  → {"customer": {"email": ...}}
+                customer.addresses[*].company   → {"customer": {"addresses": [{"company": ...}]}}
+                customer.addresses[*].city      ↑ adds "city" to the same address element
+        extract:
+          type: string
+          description: |
+            Source expression. Accepts:
+            - JSONPath starting with `$.` (e.g. `$.customer.firstName`).
+            - Handlebars template (contains `{{`) for concatenation /
+              formatting / conditional logic (e.g.
+              `{{record.firstName}} {{record.lastName}}`).
+            - A literal string (any value not starting with `$.` and not
+              containing `{{`) — treated as a hardcoded value.
+
+            Omit when using `hardCodedValue`.
+          examples:
+            - address.city
+        hardCodedValue:
+          type:
+            - string
+            - 'null'
+          description: Static value written to `generate` instead of extracting from the source record.
+          x-celigo-ai-guidance:
+            - |-
+              Static value written verbatim. Equivalent to setting ``extract``
+              to a literal string; choose whichever reads more clearly. Mutually
+              exclusive with ``extract``.
+        dataType:
+          type: string
+          enum:
+            - string
+            - number
+            - boolean
+            - numberarray
+            - stringarray
+            - json
+          x-lowercase: true
+          x-enumDescriptions:
+            string: Text string data type.
+            number: Numeric data type including integers and decimals.
+            boolean: True or false data type.
+            numberarray: Array of numeric values.
+            stringarray: Array of text string values.
+            json: Arbitrary JSON object or structure.
+          description: Data type coercion applied to the mapped value.
+        discardIfEmpty:
+          type: boolean
+          description: When true, the field is omitted from the output when the extracted value is empty.
+          x-celigo-ai-guidance:
+            - |-
+              When true, skip this field entirely when ``extract`` / lookup
+              produces empty / null. Without this flag the destination field
+              receives null and may overwrite existing data.
+        immutable:
+          type: boolean
+          description: When true, the mapped value cannot be overwritten by later mapping steps.
+        lookupName:
+          type: string
+          description: Name of an entry in the import's `lookups` array used to translate the value.
+          x-celigo-ai-guidance:
+            - |-
+              Name of a lookup defined on ``resource.lookups`` whose result
+              replaces the extracted value. The looked-up record's
+              ``resultField`` (or full record, depending on lookup shape)
+              becomes the mapped value.
+        default:
+          type:
+            - string
+            - 'null'
+          description: Fallback value used when the extract yields no value.
+        extractDateFormat:
+          type: string
+          description: Date format of the source value, used to parse it before conversion.
+          x-celigo-ai-guidance:
+            - |-
+              Moment.js-style format describing how the source date string is
+              structured (e.g. ``MM/DD/YYYY``, ``YYYY-MM-DDTHH:mm:ssZ``).
+        extractDateTimezone:
+          type: string
+          description: Timezone applied when parsing the source date value.
+          x-celigo-ai-guidance:
+            - |-
+              IANA timezone of the source value (e.g. ``America/New_York``).
+              Set together with ``generateDateTimezone`` only when a real
+              timezone conversion is required.
+        generateDateFormat:
+          type: string
+          description: Date format applied to the value written to the destination.
+        generateDateTimezone:
+          type: string
+          description: Timezone applied when formatting the destination date value.
+        conditional:
+          type: object
+          description: |
+            Only apply this mapping entry when the given condition is satisfied.
+          properties:
+            when:
+              type: string
+              enum:
+                - record_created
+                - record_updated
+                - extract_not_empty
+                - lookup_not_empty
+                - lookup_empty
+                - expression
+              x-enumDescriptions:
+                record_created: Apply only when creating a new record.
+                record_updated: Apply only when updating an existing record.
+                extract_not_empty: Apply only when `extract` produces a non-empty value.
+                lookup_not_empty: Apply only when the paired lookup returns a value.
+                lookup_empty: Apply only when the paired lookup returns no value.
+                expression: Apply only when the accompanying `expression` evaluates truthy.
+              description: |
+                Condition that gates whether this mapping entry is applied.
+                `lookup_not_empty` / `lookup_empty` evaluate the lookup named by the
+                sibling `lookupName`; `expression` evaluates the sibling `expression`.
+            lookupName:
+              type: string
+              description: |
+                Lookup to evaluate for the `lookup_not_empty` / `lookup_empty`
+                conditions.
+            expression:
+              type: string
+              description: |
+                Expression evaluated when `when` is `expression`.
+      x-celigo-ai-guidance:
+        - |-
+          One Mapper 1.0 body field assignment. Exactly one of ``extract`` or
+          ``hardCodedValue`` should carry the value; setting both is
+          rejected by the mapper processor.
+    AIDescription:
+      type: object
+      description: |
+        AI-generated descriptions and documentation for the resource.
+
+        This object contains automatically generated content that helps users
+        understand the purpose, behavior, and configuration of the resource without
+        requiring them to analyze the technical details. The AI-generated content
+        is sanitized and safe for display in the UI.
+      properties:
+        summary:
+          type:
+            - string
+            - 'null'
+          description: |
+            Brief AI-generated summary of the resource's purpose and functionality.
+
+            This concise description provides a quick overview of what the resource does,
+            what systems it interacts with, and its primary role in the integration.
+            The summary is suitable for display in list views, dashboards, and other
+            contexts where space is limited.
+
+            Maximum length: 10KB
+          examples:
+            - AI-generated overview of what this resource does and the systems it interacts with.
+        detailed:
+          type:
+            - string
+            - 'null'
+          description: |
+            Comprehensive AI-generated description of the resource's functionality.
+
+            This detailed explanation covers the resource's purpose, configuration details,
+            data flow patterns, filtering logic, and other technical aspects. It provides
+            in-depth information suitable for documentation, tooltips, or detailed views
+            in the administration interface.
+
+            The content may include HTML formatting for improved readability.
+
+            Maximum length: 10KB
+          examples:
+            - <p>A detailed AI-generated explanation of this resource's purpose, configuration, and behavior.</p><p>The text is regenerated when the resource's configuration changes.</p>
+        generatedOn:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          description: |
+            Timestamp indicating when the AI description was generated.
+
+            This field helps track the freshness of the AI-generated content and
+            determine when it might need to be regenerated due to changes in the
+            resource's configuration or behavior.
+
+            The timestamp is recorded in ISO 8601 format with UTC timezone (Z suffix).
+          examples:
+            - '2023-05-10T13:25:42Z'
+    Guardrail:
+      type: object
+      description: Guardrail import object as returned by the API.
+      required:
+        - _id
+        - name
+        - adaptorType
+        - guardrail
+        - apiIdentifier
+        - lookups
+        - createdAt
+        - lastModified
+      allOf:
+        - $ref: '#/components/schemas/ResourceResponse'
+        - $ref: '#/components/schemas/IAResourceResponse'
+        - type: object
+          properties:
+            name:
+              type: string
+              maxLength: 100
+              description: Display name for the guardrail. May be empty if created without one.
+              examples:
+                - PII Scanner
+            description:
+              type: string
+              maxLength: 5120
+              description: Free-text note describing the guardrail's purpose.
+              examples:
+                - Scans records for PII and masks detected values before import.
+            adaptorType:
+              type: string
+              enum:
+                - GuardrailImport
+              x-enumDescriptions:
+                GuardrailImport: Guardrail import adaptor for safety and compliance checks.
+              description: Always `GuardrailImport` for guardrails.
+              examples:
+                - GuardrailImport
+            _connectionId:
+              type: string
+              format: objectId
+              x-celigo-refModel: connections
+              description: BYOK connection backing an `ai_agent` guardrail. Absent when platform-managed credentials are used.
+              examples:
+                - 68ae48d6b5f755d2dd38c294
+            _sourceId:
+              type: string
+              format: objectId
+              readOnly: true
+              x-celigo-refModel: imports
+              description: Source guardrail this one was cloned from. Present only on clones.
+              examples:
+                - 69a886183b213b3ac90860fe
+            guardrail:
+              $ref: '#/components/schemas/GuardrailConfig'
+            mapping:
+              type: object
+              description: |-
+                Mapper 1.0 input mapping. Served only when populated — a
+                guardrail created without one has no `mapping` in responses.
+              properties:
+                fields:
+                  type: array
+                  description: Field-level mapping entries; `generate` targets the guardrail input (typically `text`).
+                  items:
+                    $ref: '#/components/schemas/MappingField'
+                lists:
+                  type: array
+                  description: List-level mappings, each generating a sublist. Rarely used on guardrails.
+                  items:
+                    type: object
+                    properties:
+                      generate:
+                        type: string
+                        description: Target sublist or array path to generate.
+                      fields:
+                        type: array
+                        description: Field mappings applied within each generated list item.
+                        items:
+                          $ref: '#/components/schemas/MappingField'
+              examples:
+                - fields:
+                    - extract: employeeSummary
+                      generate: text
+            inputContext:
+              type: string
+              enum:
+                - record
+                - envelope
+              x-enumDescriptions:
+                record: The guardrail receives each record directly (default behavior).
+                envelope: The guardrail receives records wrapped in an envelope with metadata.
+              description: Input shape for the guardrail's processing pipeline. Present when set; absence means `record`.
+              examples:
+                - record
+            apiIdentifier:
+              type: string
+              readOnly: true
+              description: Ten-character hex identifier used to invoke the guardrail over HTTP.
+              examples:
+                - i894602e87
+            lookups:
+              type: array
+              description: Static lookup configurations. Guardrail (AI agent) imports support static lookups only; defaults to an empty array.
+              items:
+                type: object
+              examples:
+                - []
+            mappings:
+              type: array
+              description: Import field mappings. Each entry requires a `status` field. Typically empty for guardrails.
+              items:
+                type: object
+              examples:
+                - []
+            mockResponse:
+              type: array
+              description: Sample evaluation results stored with the guardrail. The UI populates these from a preview run; accepted on create and update.
+              items:
+                type: object
+                properties:
+                  statusCode:
+                    type: integer
+                    description: HTTP-style status code of the sample evaluation.
+                    examples:
+                      - 200
+                  flagged:
+                    type: boolean
+                    description: When true, the sample input tripped the guardrail.
+                    examples:
+                      - true
+                  ignored:
+                    type: boolean
+                    description: When true, the result fell below `confidenceThreshold` and was disregarded.
+                    examples:
+                      - false
+                  masked:
+                    type: string
+                    description: Sample input with detected values masked. Populated for `pii` guardrails with masking enabled.
+                    examples:
+                      - The email is ***** and the phone number is *****
+                  dataURI:
+                    type: string
+                    description: Data URI of any artifact produced by the sample evaluation.
+                  errors:
+                    type: array
+                    description: Errors raised during the sample evaluation.
+                    items:
+                      type: object
+                    examples:
+                      - []
+            aiDescription:
+              $ref: '#/components/schemas/AIDescription'
+    Request:
+      type: object
+      description: |-
+        Configuration for a guardrail import. `_connectionId` is only
+        required for BYOK `ai_agent` guardrails.
+      properties:
+        name:
+          type: string
+          maxLength: 100
+          description: Display name for the guardrail.
+          examples:
+            - PII Scanner
+            - Content Moderator
+        description:
+          type: string
+          maxLength: 5120
+          description: Optional description of the guardrail's purpose.
+          examples:
+            - Scans records for PII and masks detected values before import.
+        _connectionId:
+          type: string
+          format: objectId
+          x-celigo-refModel: connections
+          description: Connection for BYOK (bring your own key). Only needed for `ai_agent` type guardrails. Optional — platform-managed credentials are used when omitted.
+          examples:
+            - 68ae48d6b5f755d2dd38c294
+        adaptorType:
+          type: string
+          enum:
+            - GuardrailImport
+          x-enumDescriptions:
+            GuardrailImport: Guardrail import adaptor for safety and compliance checks.
+          description: Must be `GuardrailImport`.
+          examples:
+            - GuardrailImport
+        guardrail:
+          $ref: '#/components/schemas/GuardrailConfig'
+        mapping:
+          type: object
+          description: |-
+            Mapper 1.0 mapping that selects the guardrail's input from the
+            incoming record. The UI writes a single field entry that maps a
+            record field to the `text` input (e.g.
+            `{"fields": [{"extract": "employeeSummary", "generate": "text"}]}`).
+            Optional — when omitted the whole record is evaluated. The server
+            serves this field only when populated.
+          properties:
+            fields:
+              type: array
+              description: Field-level mapping entries; `generate` targets the guardrail input (typically `text`).
+              items:
+                $ref: '#/components/schemas/MappingField'
+            lists:
+              type: array
+              description: List-level mappings, each generating a sublist. Rarely used on guardrails.
+              items:
+                type: object
+                properties:
+                  generate:
+                    type: string
+                    description: Target sublist or array path to generate.
+                  fields:
+                    type: array
+                    description: Field mappings applied within each generated list item.
+                    items:
+                      $ref: '#/components/schemas/MappingField'
+          examples:
+            - fields:
+                - extract: employeeSummary
+                  generate: text
+        inputContext:
+          type: string
+          enum:
+            - record
+            - envelope
+          x-enumDescriptions:
+            record: The guardrail receives each record directly (default behavior).
+            envelope: The guardrail receives records wrapped in an envelope with metadata.
+          description: |-
+            Controls the shape of the input passed to the guardrail's
+            processing pipeline, exactly as on other imports. The UI writes
+            `record` explicitly on new guardrails; when the field is absent
+            the platform behaves as `record`.
+          examples:
+            - record
+      required:
+        - name
+        - adaptorType
+        - guardrail
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    DependencyEntry:
+      type: object
+      description: A single resource that depends on the queried resource.
+      properties:
+        id:
+          type: string
+          description: Unique identifier of the dependent resource.
+          examples:
+            - 61f92026dd053843b5d72350
+        name:
+          type: string
+          description: Display name of the dependent resource.
+          examples:
+            - Import Orders to NetSuite
+        paths:
+          type: array
+          description: |-
+            Dot-notation paths within the dependent resource that reference
+            the target resource. `[*]` denotes array elements.
+          items:
+            type: string
+          examples:
+            - - hooks.preSavePage._scriptId
+        accessLevel:
+          type: string
+          description: The caller's access level on the dependent resource.
+          examples:
+            - manage
+        dependencyIds:
+          type: object
+          description: |-
+            Map of resource types to arrays of IDs that this dependent
+            resource references on the target. Keys are singular or plural
+            resource type strings; values are arrays of ID strings.
+          additionalProperties:
+            type: array
+            items:
+              type: string
+          example:
+            script:
+              - 64ff4b21612a134bd2f45531
+      required:
+        - id
+        - name
+        - paths
+        - accessLevel
+        - dependencyIds
+    DependencyResponse:
+      type: object
+      description: |
+        Map of dependent-resource types to arrays of dependency entries.
+        Keys are plural resource type strings (e.g. `flows`, `imports`,
+        `connections`). An empty object `{}` means no dependents.
+      additionalProperties:
+        type: array
+        items:
+          $ref: '#/components/schemas/DependencyEntry'
+      example:
+        exports:
+          - id: 64ff4b21612a134bd2f45534
+            name: Bank FTP Export
+            paths:
+              - hooks.preSavePage._scriptId
+            accessLevel: manage
+            dependencyIds:
+              script:
+                - 64ff4b21612a134bd2f45531
+        flows:
+          - id: 64ff4b22612a134bd2f45538
+            name: CAMT-053 to Celigo CAM Format
+            paths:
+              - pageGenerators[*]._exportId
+            accessLevel: manage
+            dependencyIds:
+              export:
+                - 64ff4b21612a134bd2f45534
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+    422-dependency-conflict:
+      description: |-
+        The resource has dependents that must be deleted first. Each entry
+        in the `errors` array names one blocking resource.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: dependencies_not_deleted
+                    message: export 6902d88c10b42b2eaac9b2a1 must be deleted before you can delete connection 6398ddf316be761fb16a6523
+x-enable-proxy: true
+x-internal: false