@celigo/api-specs 0.2.75 → 0.2.77

package/dist/ai-agent.yml

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

package/dist/connection.yml

@@ -1536,6 +1536,345 @@ paths:
         - |-
           Read the status as the target's, not the proxy's: a 422 or 404 with a non-invalid_ref
           body is the downstream system's validation result for the forwarded request.
+  /v1/connections/{_id}/import:
+    post:
+      x-internal: false
+      operationId: invokeVirtualImport
+      tags:
+        - Connections
+      summary: Run an import document through a connection
+      description: |-
+        Runs an import document sent in the request body — a virtual import —
+        through this connection against the supplied records and returns one
+        result per record, synchronously. Nothing is saved: the document can be
+        an unsaved draft, a modified copy, or a saved import as fetched (`_id`
+        and metadata accepted). Each record runs the document's own pipeline —
+        input filter, preMap hook, mappings, postMap hook, request, postSubmit
+        hook — and the request executes against the live destination: a real
+        write, not a dry run; a saved `mockResponse` does not substitute. A
+        record the input filter excludes comes back `ignored`, never sent.
+        Adaptors `POST /v1/imports/preview` rejects with `invalid_adaptor` run
+        here — NetSuite and RDBMS verified alongside HTTP.
+
+        The step runs with the document's own `settings` only: hooks receive
+        `options.settings` with an `import` key but no `integration` or `flow`
+        key and no `_flowId` / `_integrationId`; `{{settings.integration.*}}`
+        and `{{settings.flow.*}}` templates render empty. A document that reads
+        integration- or flow-level settings behaves differently here than in a
+        flow run, and nothing in the request supplies that context. The
+        connection in the path is the one used; a `_connectionId` on the
+        document is ignored.
+
+        `POST /v1/imports/{_id}/invoke` runs a saved import the same way with
+        the same per-record shape; the read-side sibling is the virtual export,
+        `POST /v1/connections/{_id}/export`.
+      parameters:
+        - in: path
+          name: _id
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+            examples:
+              - 6a04b5309dc296c4efb1a6e0
+          description: Connection the import document runs through.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              description: The import document to run and the records to run through it.
+              x-celigo-ai-guidance:
+                - |-
+                  This executes the request against the live destination — a real write, even when the
+                  document carries a saved `mockResponse`. Treat it like a flow run, never like a preview.
+                - |-
+                  The step gets the document's own settings only: hooks see `options.settings = {import}`
+                  with no `integration` / `flow` key and no `_flowId` / `_integrationId`, and
+                  `{{settings.integration.*}}` / `{{settings.flow.*}}` render empty. A step whose hooks or
+                  templates read those settings builds a different record here than in a flow run — do
+                  not send it this way.
+                - |-
+                  NetSuite and RDBMS documents run here, where `POST /v1/imports/preview` answers
+                  `invalid_adaptor`. A record the input filter excludes comes back
+                  `{ignored: true, stage: "inputFilter"}` and was never sent; omitting `data` is a
+                  `400 invalid_request`.
+              required:
+                - import
+                - data
+              properties:
+                import:
+                  type: object
+                  description: |-
+                    The import document to run (mirror of the `POST /v1/imports`
+                    body shape); `name` and `_connectionId` are not needed, and a
+                    saved import's `_id` and metadata may ride along unchanged.
+                    Adaptor-specific blocks (`http`, `netsuite_da`, `rdbms`, …),
+                    `mapping`, `filter` and `hooks` apply exactly as on a saved
+                    import.
+                  additionalProperties: true
+                data:
+                  type: array
+                  description: |-
+                    Records to run through the document, each becoming one result.
+                    An empty array returns an empty array; omitting `data` is
+                    rejected.
+                  items:
+                    type: object
+                    additionalProperties: true
+              additionalProperties: true
+            examples:
+              unsaved_http_import:
+                summary: Run an unsaved HTTP import against one record
+                value:
+                  import:
+                    adaptorType: HTTPImport
+                    mapping:
+                      fields:
+                        - extract: email
+                          generate: Email
+                      lists: []
+                    http:
+                      relativeURI:
+                        - /post
+                      method:
+                        - POST
+                      requestType:
+                        - CREATE
+                      requestMediaType: json
+                      successMediaType: json
+                      sendPostMappedData: true
+                      formType: http
+                  data:
+                    - email: contact@acme.com
+      responses:
+        '200':
+          description: |-
+            One result per input record, in input order — accepted, failed at
+            the destination, or ignored by the document's own input filter.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ImportRecordResult'
+              examples:
+                accepted:
+                  summary: Record accepted — the destination's response body in _json
+                  value:
+                    - statusCode: 200
+                      _json:
+                        Email: contact@acme.com
+                      _headers:
+                        content-type: application/json; charset=utf-8
+                destination_rejected:
+                  summary: Destination rejected the record
+                  value:
+                    - statusCode: 422
+                      _json: {}
+                      errors:
+                        - message: 'Failed to create, update/transform record because com.netledger.common.exceptions.NLUserError: The record type [CUSTOMRECORD_ZZ] is invalid.'
+                          code: javaexception
+                          source: application
+                          resolved: false
+                          occurredAt: 1791309460117
+                          stage: apiCall
+                          classification: missing
+                ignored_by_input_filter:
+                  summary: Record excluded by the input filter — nothing sent
+                  value:
+                    - statusCode: 200
+                      _json: {}
+                      ignored: true
+                      stage: inputFilter
+        '400':
+          description: |-
+            Request body is malformed — the top-level `import` object or the
+            `data` array is missing. Returned as a bare array of error objects,
+            not the standard `errors` envelope.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    code:
+                      type: string
+                    message:
+                      type: string
+              examples:
+                missing_import:
+                  value:
+                    - code: invalid_request
+                      message: Request body should contain an import object details.
+                missing_data:
+                  value:
+                    - code: invalid_request
+                      message: Request body should contain data which is to be imported.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: '`invalid_ref` — `_id` is not a connection in the account.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                connection_not_found:
+                  value:
+                    errors:
+                      - field: connection
+                        code: invalid_ref
+                        message: connection not found.
+                      - field: _connectionId
+                        code: invalid_ref
+                        message: a9e11dc0de1ec0de00000009 is not a valid _connectionId
+  /v1/connections/{_id}/export:
+    post:
+      x-internal: false
+      operationId: invokeVirtualExport
+      tags:
+        - Connections
+      summary: Run an export document through a connection
+      description: |-
+        Runs an export document sent in the request body — a virtual export —
+        through this connection against the live source and returns the fetched
+        records, synchronously. Nothing is saved and no job is created: the
+        document can be an unsaved draft, a modified copy of a saved export, or
+        a saved export as fetched. Use it to read from a system through an
+        existing connection before an export exists, or to check what a changed
+        export definition would return.
+
+        The connection in the path is the one used; a `_connectionId` on the
+        document is not needed. The read executes against the live source
+        (HTTP and NetSuite RESTlet searches verified) and `dataURIs` carries,
+        per record, a link to the record in the source system when the adaptor
+        provides one (`null` otherwise).
+
+        The export-side preview surfaces, `POST /v1/exports/preview` and the
+        flow-scoped `POST /v1/integrations/{_integrationId}/flows/{_flowId}/exports/preview`,
+        return the same records inside a stage-by-stage envelope; prefer them
+        when the export's transform or filter output matters. The write-side
+        sibling is the virtual import, `POST /v1/connections/{_id}/import`.
+      parameters:
+        - in: path
+          name: _id
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: connections
+            examples:
+              - 6a04b5309dc296c4efb1a6e0
+          description: Connection the export document runs through.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              description: The export document to run.
+              required:
+                - export
+              properties:
+                export:
+                  type: object
+                  description: |-
+                    The export document to run (mirror of the `POST /v1/exports`
+                    body shape); `name` and `_connectionId` are not needed.
+                    Adaptor-specific blocks (`http`, `netsuite`, `rdbms`, …) apply
+                    exactly as on a saved export.
+                  additionalProperties: true
+              additionalProperties: true
+            examples:
+              netsuite_search:
+                summary: Run an ad-hoc NetSuite search by externalid
+                value:
+                  export:
+                    adaptorType: NetSuiteExport
+                    netsuite:
+                      type: restlet
+                      skipGrouping: true
+                      restlet:
+                        recordType: customrecord_payout_variance
+                        restletVersion: suitebundle
+                        columns:
+                          - name: internalid
+                            label: internalid
+                          - name: externalid
+                            label: externalid
+                        criteria:
+                          - field: externalid
+                            operator: is
+                            searchValue: SEED-01
+      responses:
+        '200':
+          description: The records the source returned, with a per-record link when the adaptor provides one.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    description: Records fetched from the source, in the order the source returned them.
+                    items:
+                      type: object
+                      additionalProperties: true
+                  dataURIs:
+                    type: array
+                    description: |-
+                      One entry per record in `data`: a link to the record in the
+                      source system when the adaptor provides one, otherwise `null`.
+                    items:
+                      type:
+                        - string
+                        - 'null'
+                additionalProperties: true
+              examples:
+                netsuite_rows:
+                  summary: NetSuite search result with record links
+                  value:
+                    data:
+                      - id: '1'
+                        recordType: customrecord_payout_variance
+                        internalid: '1'
+                        externalid: SEED-01
+                    dataURIs:
+                      - https://1234567.app.netsuite.com/app/common/custom/custrecordentry.nl?rectype=923&id=1
+        '400':
+          description: The top-level `export` object is missing.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                missing_export:
+                  value:
+                    errors:
+                      - code: invalid_request
+                        message: Request body should contain an export object details.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: '`invalid_ref` — `_id` is not a connection in the account.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                connection_not_found:
+                  value:
+                    errors:
+                      - field: _connectionId
+                        code: invalid_ref
+                        message: a9e11dc0de1ec0de00000009 is not a valid _connectionId
+                      - field: connection
+                        code: invalid_ref
+                        message: connection not found.
   /v1/connections/{_id}/debug:
     get:
       x-internal: false
@@ -8806,6 +9145,82 @@ components:
       minItems: 1
       items:
         $ref: '#/components/schemas/JsonPatchOperation'
+    ImportRecordResult:
+      type: object
+      description: |-
+        The outcome of running one input record through an import — one element
+        per record, in input order — shared by `POST /v1/imports/{_id}/invoke`
+        and the virtual import `POST /v1/connections/{_id}/import`. A record the
+        import itself ignored before any request carries `ignored: true` and the
+        `stage` that dropped it; a record the destination accepted carries its
+        parsed response; a record the destination rejected — or that the
+        import's `failPath` / `failValues` rules judged a failure even on a
+        `2xx` — carries `errors[]`.
+      properties:
+        statusCode:
+          type: integer
+          description: |-
+            HTTP status of the record's outcome. The destination's status for an
+            accepted record; `422` when the import recorded a failure for the
+            record — including when the destination itself answered `200` and
+            the import's `failPath` rules declared it a failure.
+        _json:
+          type: object
+          description: |-
+            The destination's parsed response body for the record — the slice
+            under the import's `response.resourcePath` when one is defined — not
+            the record that was sent. `{}` when the record was ignored or the
+            destination returned no usable body.
+          additionalProperties: true
+        _headers:
+          type: object
+          description: Response headers the destination returned for the record.
+          additionalProperties: true
+        ignored:
+          type: boolean
+          description: |-
+            When true, the import dropped the record before sending anything and
+            `stage` names the gate; the destination was not called for it.
+        stage:
+          type: string
+          description: |-
+            The import stage that ignored the record — `inputFilter` when the
+            import's own input filter excluded it. Present only with `ignored`.
+          examples:
+            - inputFilter
+        errors:
+          type: array
+          description: |-
+            Errors recorded for the record. `source: application` with
+            `stage: apiCall` means the request reached the destination and its
+            answer was the failure; the destination's response body rides in
+            `message`.
+          items:
+            type: object
+            properties:
+              source:
+                type: string
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  The adaptor's error code, or the destination's HTTP status as
+                  an integer when the import's `failPath` rules turned a
+                  successful-looking response into a failure.
+              message:
+                type: string
+              resolved:
+                type: boolean
+              occurredAt:
+                type: integer
+                format: int64
+              stage:
+                type: string
+              classification:
+                type: string
+            additionalProperties: true
+      additionalProperties: true
     ConnectionMetadataRequest:
       type: object
       description: |-