@celigo/api-specs 0.2.75 → 0.2.77

package/dist/import.yml

@@ -533,16 +533,27 @@ paths:
         data records and returns per-record results synchronously.
 
         The request body should contain a `data` array of records to import. Each
-        record is processed through the import's mappings, transformations, and
-        hooks before being sent to the destination.
-
-        The response is an **array** of per-record result objects, each containing
-        a `statusCode`, the transformed `_json` payload, and any `errors`
-        encountered during processing. This endpoint writes to the destination
-        system — and so does `POST /v1/imports/preview` (verified to execute the
-        composed request), so neither is a dry run against a production
-        destination. A 200 response may still contain per-record failures in
-        each element's `errors` array.
+        record is processed through the import's input filter, mappings, hooks
+        (preMap, postMap, postSubmit) and transformations before being sent to
+        the destination; a record the input filter excludes comes back `ignored`
+        and is never sent.
+
+        The response is an **array** of per-record result objects — `statusCode`,
+        the destination's parsed response body as `_json`, `errors` when the
+        record failed. This endpoint writes to the destination system — and so
+        does `POST /v1/imports/preview` (verified to execute the composed
+        request), so neither is a dry run against a production destination. A
+        200 response may still contain per-record failures in each element's
+        `errors` array. Every import adaptor runs here (HTTP, NetSuite, RDBMS,
+        FTP verified), including the ones `POST /v1/imports/preview` rejects with
+        `invalid_adaptor`. For a file import the 200 reflects the file being
+        composed, not delivered — an FTP import against an unreachable host
+        still returns `{name, fileLocation}`.
+
+        The import must be saved; to run an import definition that is not saved
+        (or a modified copy of one), use the virtual import
+        `POST /v1/connections/{_id}/import`, which takes the import document in
+        the body and returns the same per-record results.
       parameters:
         - in: path
           name: _id
@@ -579,45 +590,25 @@ paths:
       responses:
         '200':
           description: |-
-            Import completed. Returns a per-record result array. Each element
-            contains the `statusCode` from the destination, the transformed
-            `_json` payload, and any `errors` encountered.
+            Import completed. One result per input record, in input order —
+            accepted, failed at the destination, or ignored by the import's own
+            input filter.
           content:
             application/json:
               schema:
                 type: array
                 items:
-                  type: object
-                  properties:
-                    statusCode:
-                      type: integer
-                      description: HTTP status code from the destination system
-                    _json:
-                      type: object
-                      description: The transformed record as sent to the destination
-                      additionalProperties: true
-                    errors:
-                      type: array
-                      description: Errors encountered processing this record
-                      items:
-                        type: object
-                        properties:
-                          source:
-                            type: string
-                          code:
-                            type: string
-                          message:
-                            type: string
-                          resolved:
-                            type: boolean
-                          occurredAt:
-                            type: integer
-                            format: int64
-                          stage:
-                            type: string
-                          classification:
-                            type: string
+                  $ref: '#/components/schemas/ImportRecordResult'
               examples:
+                accepted:
+                  summary: Record accepted — the destination's response body in _json
+                  value:
+                    - statusCode: 200
+                      _json:
+                        id: 0031U00001AbCdEQAV
+                        success: true
+                      _headers:
+                        content-type: application/json; charset=utf-8
                 destination_error:
                   summary: Record failed at destination
                   value:
@@ -631,6 +622,13 @@ paths:
                           occurredAt: 1777645680144
                           stage: apiCall
                           classification: value
+                ignored_by_input_filter:
+                  summary: Record excluded by the import's input filter — nothing sent
+                  value:
+                    - statusCode: 200
+                      _json: {}
+                      ignored: true
+                      stage: inputFilter
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
@@ -780,10 +778,14 @@ paths:
         '422':
           description: |-
             Request body is malformed — most commonly the top-level `import`
-            object is missing — or the adaptor type is unsupported: RDBMS-family
-            imports are rejected with `invalid_adaptor` ("Import preview is not
-            supported for adaptor type: RDBMSImport"); database imports have no
-            request-preview surface anywhere (the SQL editor's Handlebars
+            object is missing — or the adaptor type is unsupported: NetSuite,
+            Salesforce, RDBMS and FTP imports are rejected with `invalid_adaptor`
+            ("Import preview is not supported for adaptor type: <adaptorType>")
+            before any connection is resolved, while HTTP-family and AI-agent
+            imports preview normally. The rejected adaptors execute through the
+            virtual import, `POST /v1/connections/{_id}/import`, which runs the
+            document for real and returns per-record results; database imports
+            have no compose-only surface anywhere (the SQL editor's Handlebars
             evaluation is their only preview). Structural validation returns the
             standard errors envelope.
           content:
@@ -801,6 +803,11 @@ paths:
                     errors:
                       - code: invalid_adaptor
                         message: 'Import preview is not supported for adaptor type: RDBMSImport.'
+                netsuite_unsupported:
+                  value:
+                    errors:
+                      - code: invalid_adaptor
+                        message: 'Import preview is not supported for adaptor type: NetSuiteDistributedImport.'
   /v1/netsuiteDA/previewImportMappingFields:
     put:
       x-internal: false
@@ -9039,8 +9046,9 @@ components:
 
         A `_connectionId` on the parent import selects bring-your-own-key (BYOK)
         credentials. Without one, built-in providers run on platform-managed
-        credentials; catalog providers have no platform-managed credentials, so they
-        save without a connection but cannot run until one is attached.
+        credentials; catalog providers have no platform-managed credentials, so the
+        save requires one — without it the agent fails to save with 422
+        `connection_required` on `_connectionId`.
       required:
         - provider
       properties:
@@ -9077,10 +9085,11 @@ components:
               generic flat format — `model` and `modelOptions` directly on this object,
               never an `openai` or `litellm` block.
             - |-
-              Catalog providers are BYOK-only at run time: the agent saves without a
-              `_connectionId`, but its first run fails with 422 `invalid_request` ("No API
-              key configured for provider …"). Always attach an HTTP connection to the
-              vendor's API (token auth) when the provider is a catalog provider.
+              Catalog providers are BYOK-only, and the save enforces it: without a `_connectionId`
+              the agent fails to save with 422 `connection_required` on `_connectionId` ("No API
+              key is available for provider 'xai'. Add a connection for this provider with your
+              API key and select it on this agent."). Attach an HTTP connection to the vendor's
+              API (token auth) before saving a catalog-provider agent.
         model:
           type: string
           description: |-
@@ -9092,11 +9101,11 @@ components:
               Required for every catalog provider — omitting it or sending an empty string
               fails the save with 422 `missing_required_field`.
             - |-
-              Without a `_connectionId` on the parent import the model must be one the
-              catalog lists for the provider: an unknown id fails the save with 422
-              `model_not_found`, a listed-but-disabled id with 422 `model_disabled`. With a
-              `_connectionId` (BYOK) any model string saves — the server does not check it
-              against the catalog or the vendor.
+              The connection is checked before the model: without a `_connectionId` on the
+              parent import a catalog-provider agent fails to save with 422
+              `connection_required` whatever the model string (an unknown id included).
+              With a `_connectionId` (BYOK) any model string saves — the server does not
+              check it against the catalog or the vendor.
         modelOptions:
           type: object
           description: |-
@@ -9420,12 +9429,22 @@ components:
                         - manual
                         - json
                       x-enumDescriptions:
-                        manual: The schema was built field-by-field in the visual editor.
-                        json: The schema was pasted or edited as raw JSON.
+                        manual: The UI opens `jsonSchema` in the visual field-by-field editor
+                        json: The UI opens `jsonSchema` in the raw JSON editor
                       description: |-
-                        How the structured-output schema was authored in the UI.
-                        Editor state only — it does not change how `jsonSchema` is
-                        sent to the provider.
+                        Which editor the UI opens `jsonSchema` in; the schema sent to the provider
+                        is the same either way, and the field is only meaningful when `type` is
+                        "json_schema". Unset opens the visual editor, and an edit there rebuilds
+                        `jsonSchema` from the field list, keeping only `type`, `properties`,
+                        `required`, `items`, `description`, `enum`, `pattern`, length and numeric
+                        bounds, `multipleOf`, `minItems`/`maxItems` and a `"null"` type — other
+                        keywords are dropped without a prompt, and `integer` becomes `number`.
+                      x-celigo-ai-guidance:
+                        - |-
+                          Set `json` on a schema written as raw JSON; keep a user's `manual` and stay
+                          inside the keywords the visual editor keeps. A full PUT that omits the field
+                          clears it, and a value outside the enum fails the save with 422 `enum` on
+                          `aiAgent.openai.output.format.schemaMode`.
                     name:
                       type: string
                       description: Name for the output format (used with json_schema)
@@ -9778,12 +9797,22 @@ components:
                     - manual
                     - json
                   x-enumDescriptions:
-                    manual: The schema was built field-by-field in the visual editor.
-                    json: The schema was pasted or edited as raw JSON.
+                    manual: The UI opens `jsonSchema` in the visual field-by-field editor
+                    json: The UI opens `jsonSchema` in the raw JSON editor
                   description: |-
-                    How the structured-output schema was authored in the UI. Editor
-                    state only — it does not change how `jsonSchema` is sent to the
-                    provider.
+                    Which editor the UI opens `jsonSchema` in; the schema sent to the provider is
+                    the same either way, and the field is only meaningful when `type` is
+                    "json_schema". Unset opens the visual editor, and an edit there rebuilds
+                    `jsonSchema` from the field list, keeping only `type`, `properties`, `required`,
+                    `items`, `description`, `enum`, `pattern`, length and numeric bounds,
+                    `multipleOf`, `minItems`/`maxItems` and a `"null"` type — other keywords are
+                    dropped without a prompt, and `integer` becomes `number`.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Set `json` on a schema written as raw JSON; keep a user's `manual` and stay inside
+                      the keywords the visual editor keeps. A full PUT that omits the field clears it,
+                      and a value outside the enum fails the save with 422 `enum` on
+                      `aiAgent.litellm.responseFormat.schemaMode`.
                 name:
                   type: string
                   description: Name for the output format (used with json_schema).
@@ -10460,8 +10489,9 @@ components:
 
         A `_connectionId` on the parent import selects bring-your-own-key (BYOK)
         credentials. Without one, built-in providers run on platform-managed
-        credentials; catalog providers have no platform-managed credentials, so they
-        save without a connection but cannot run until one is attached.
+        credentials; catalog providers have no platform-managed credentials, so the
+        save requires one — without it the guardrail fails to save with 422
+        `connection_required` on `_connectionId`.
       x-celigo-ai-guidance:
         - |-
           Do not send `tools` on any block. A non-empty array at `tools`, `openai.tools`,
@@ -10504,10 +10534,11 @@ components:
               generic flat format — `model` and `modelOptions` directly on this object,
               never an `openai` or `litellm` block.
             - |-
-              Catalog providers are BYOK-only at run time: the guardrail saves without a
-              `_connectionId`, but its first run fails with 422 `invalid_request` ("No API
-              key configured for provider …"). Always attach an HTTP connection to the
-              vendor's API (token auth) when the provider is a catalog provider.
+              Catalog providers are BYOK-only, and the save enforces it: without a `_connectionId`
+              the guardrail fails to save with 422 `connection_required` on `_connectionId` ("No
+              API key is available for provider 'xai'. Add a connection for this provider with
+              your API key and select it on this agent."). Attach an HTTP connection to the
+              vendor's API (token auth) before saving a catalog-provider guardrail.
         model:
           type: string
           description: |-
@@ -10519,11 +10550,11 @@ components:
               Required for every catalog provider — omitting it or sending an empty string
               fails the save with 422 `missing_required_field`.
             - |-
-              Without a `_connectionId` on the parent import the model must be one the
-              catalog lists for the provider: an unknown id fails the save with 422
-              `model_not_found`, a listed-but-disabled id with 422 `model_disabled`. With a
-              `_connectionId` (BYOK) any model string saves — the server does not check it
-              against the catalog or the vendor.
+              The connection is checked before the model: without a `_connectionId` on the
+              parent import a catalog-provider guardrail fails to save with 422
+              `connection_required` whatever the model string (an unknown id included).
+              With a `_connectionId` (BYOK) any model string saves — the server does not
+              check it against the catalog or the vendor.
         modelOptions:
           type: object
           description: |-
@@ -10788,12 +10819,17 @@ components:
                         - manual
                         - json
                       x-enumDescriptions:
-                        manual: The schema was built field-by-field in the visual editor.
-                        json: The schema was pasted or edited as raw JSON.
+                        manual: The schema editor opens `jsonSchema` in the visual field-by-field view
+                        json: The schema editor opens `jsonSchema` in the raw JSON view
                       description: |-
-                        How the structured-output schema was authored in the UI.
-                        Editor state only — it does not change how `jsonSchema` is
-                        sent to the provider.
+                        Which view a schema editor opens `jsonSchema` in; the schema sent to the
+                        provider is the same either way. Stored and echoed on guardrails for parity
+                        with the AI-agent format block — the guardrail form does not set it today.
+                      x-celigo-ai-guidance:
+                        - |-
+                          Resend the stored value on every update — a full PUT that omits the field
+                          clears it — and never invent one: a value outside the enum fails the save with
+                          422 `enum` on `guardrail.aiAgent.openai.output.format.schemaMode`.
                     name:
                       type: string
                       description: Name for the output format (used with json_schema)
@@ -10982,12 +11018,17 @@ components:
                     - manual
                     - json
                   x-enumDescriptions:
-                    manual: The schema was built field-by-field in the visual editor.
-                    json: The schema was pasted or edited as raw JSON.
+                    manual: The schema editor opens `jsonSchema` in the visual field-by-field view
+                    json: The schema editor opens `jsonSchema` in the raw JSON view
                   description: |-
-                    How the structured-output schema was authored in the UI. Editor
-                    state only — it does not change how `jsonSchema` is sent to the
-                    provider.
+                    Which view a schema editor opens `jsonSchema` in; the schema sent to the provider
+                    is the same either way. Stored and echoed on guardrails for parity with the
+                    AI-agent format block — the guardrail form does not set it today.
+                  x-celigo-ai-guidance:
+                    - |-
+                      Resend the stored value on every update — a full PUT that omits the field clears
+                      it — and never invent one: a value outside the enum fails the save with 422 `enum`
+                      on `guardrail.aiAgent.litellm.responseFormat.schemaMode`.
                 name:
                   type: string
                   description: Name for the output format (used with json_schema).
@@ -16663,6 +16704,82 @@ components:
           description: The stack id associated with the resource, or null if no stack is involved.
           examples:
             - 5f8d43a1b9e5a80011a35f2c
+    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
     ImportPreviewResponse:
       type: object
       description: |-