@celigo/api-specs 0.2.100 → 0.2.102

package/dist/ai-agent.yml

@@ -2118,7 +2118,11 @@ components:
             - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
             - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
             - For array fields: Set to the array property name, then configure 'buildArrayHelper'
-            - For arrays within arrays: Leave EMPTY for the inner array mappings, as they don't have field names
+            - Two structural blanks: the inner array item of an array of arrays (it has no field name),
+              and the single top-level `objectarray` item of a `rows [ ]` mapping (the array output
+              structure — see the array's description). A child-bearing wrapper and a source-only row that
+              already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
+              name changes the output; it does not complete the row
 
             IMPORTANT: Do NOT use dot notation (e.g., "customer.firstName") in this field. Instead, create proper
             hierarchical structure with nested mappings:
@@ -2133,8 +2137,9 @@ components:
             }
             ```
 
-            When parsing existing mappings, empty 'generate' fields almost always indicate inner array structures
-            within a parent array.
+            When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+            empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
+            structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
           examples:
             - name
             - address
@@ -3115,6 +3120,12 @@ components:
         object-array row left with no source, no destination and no remaining child `mappings` or
         `buildArrayHelper` entries; a row with only one of the two, and a source-less, destination-less
         wrapper that still has children, are kept.
+
+        The shape of the array is the mapper's **JSON structure**. Named top-level items produce an object
+        record (`record { }`). Exactly one top-level item with `dataType: objectarray` and no `generate` is
+        the `rows [ ]` structure: the mapped record is an array — usually one element per element of the
+        source array that root's `buildArrayHelper` iterates — Handlebars templates such as `http.body`
+        bind it as `rows` instead of `record`, and the mapping editor shows that row's destination disabled.
       x-celigo-ai-guidance:
         - |-
           Rows that exist in the saved document — including `Draft` and `Inactive` rows and
@@ -3123,6 +3134,14 @@ components:
           them. Only a row with neither source nor destination — and, for an object or
           object-array row, no remaining children — can be left out; the save would drop it
           anyway. A wrapper with children but no `generate` is kept by the save, so keep it.
+        - |-
+          A single unnamed top-level `objectarray` item is the `rows [ ]` JSON structure, not a
+          missing destination: keep it unnamed when editing (naming it turns the output into an
+          object, and a template that iterates `rows` then renders nothing), and author that
+          shape only when the request body must be an array or a template iterates `rows`.
+          The editor's save check accepts the unnamed root only in the `rows [ ]` structure;
+          any other row with a source and no `generate` fails with "One or more destination
+          field values not entered".
       items:
         type: object
         properties:
@@ -3138,7 +3157,11 @@ components:
               - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
               - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
               - For array fields: Set to the array property name, then configure 'buildArrayHelper'
-              - For arrays within arrays: Leave EMPTY for the inner array mappings, as they don't have field names
+              - Two structural blanks: the inner array item of an array of arrays (it has no field name),
+                and the single top-level `objectarray` item of a `rows [ ]` mapping (the array output
+                structure — see the array's description). A child-bearing wrapper and a source-only row that
+                already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
+                name changes the output; it does not complete the row
 
               IMPORTANT: Do NOT use dot notation (e.g., "customer.firstName") in this field. Instead, create proper
               hierarchical structure with nested mappings:
@@ -3153,8 +3176,9 @@ components:
               }
               ```
 
-              When parsing existing mappings, empty 'generate' fields almost always indicate inner array structures
-              within a parent array.
+              When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+              empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
+              structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
             examples:
               - name
               - address

package/dist/asynchelper.yml

@@ -505,7 +505,11 @@ components:
             - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
             - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
             - For array fields: Set to the array property name, then configure 'buildArrayHelper'
-            - For arrays within arrays: Leave EMPTY for the inner array mappings, as they don't have field names
+            - Two structural blanks: the inner array item of an array of arrays (it has no field name),
+              and the single top-level `objectarray` item of a `rows [ ]` mapping (the array output
+              structure — see the array's description). A child-bearing wrapper and a source-only row that
+              already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
+              name changes the output; it does not complete the row
 
             IMPORTANT: Do NOT use dot notation (e.g., "customer.firstName") in this field. Instead, create proper
             hierarchical structure with nested mappings:
@@ -520,8 +524,9 @@ components:
             }
             ```
 
-            When parsing existing mappings, empty 'generate' fields almost always indicate inner array structures
-            within a parent array.
+            When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+            empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
+            structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
           examples:
             - name
             - address
@@ -1502,6 +1507,12 @@ components:
         object-array row left with no source, no destination and no remaining child `mappings` or
         `buildArrayHelper` entries; a row with only one of the two, and a source-less, destination-less
         wrapper that still has children, are kept.
+
+        The shape of the array is the mapper's **JSON structure**. Named top-level items produce an object
+        record (`record { }`). Exactly one top-level item with `dataType: objectarray` and no `generate` is
+        the `rows [ ]` structure: the mapped record is an array — usually one element per element of the
+        source array that root's `buildArrayHelper` iterates — Handlebars templates such as `http.body`
+        bind it as `rows` instead of `record`, and the mapping editor shows that row's destination disabled.
       x-celigo-ai-guidance:
         - |-
           Rows that exist in the saved document — including `Draft` and `Inactive` rows and
@@ -1510,6 +1521,14 @@ components:
           them. Only a row with neither source nor destination — and, for an object or
           object-array row, no remaining children — can be left out; the save would drop it
           anyway. A wrapper with children but no `generate` is kept by the save, so keep it.
+        - |-
+          A single unnamed top-level `objectarray` item is the `rows [ ]` JSON structure, not a
+          missing destination: keep it unnamed when editing (naming it turns the output into an
+          object, and a template that iterates `rows` then renders nothing), and author that
+          shape only when the request body must be an array or a template iterates `rows`.
+          The editor's save check accepts the unnamed root only in the `rows [ ]` structure;
+          any other row with a source and no `generate` fails with "One or more destination
+          field values not entered".
       items:
         type: object
         properties:
@@ -1525,7 +1544,11 @@ components:
               - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
               - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
               - For array fields: Set to the array property name, then configure 'buildArrayHelper'
-              - For arrays within arrays: Leave EMPTY for the inner array mappings, as they don't have field names
+              - Two structural blanks: the inner array item of an array of arrays (it has no field name),
+                and the single top-level `objectarray` item of a `rows [ ]` mapping (the array output
+                structure — see the array's description). A child-bearing wrapper and a source-only row that
+                already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
+                name changes the output; it does not complete the row
 
               IMPORTANT: Do NOT use dot notation (e.g., "customer.firstName") in this field. Instead, create proper
               hierarchical structure with nested mappings:
@@ -1540,8 +1563,9 @@ components:
               }
               ```
 
-              When parsing existing mappings, empty 'generate' fields almost always indicate inner array structures
-              within a parent array.
+              When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+              empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
+              structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
             examples:
               - name
               - address

package/dist/export.yml

@@ -12311,7 +12311,11 @@ components:
             - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
             - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
             - For array fields: Set to the array property name, then configure 'buildArrayHelper'
-            - For arrays within arrays: Leave EMPTY for the inner array mappings, as they don't have field names
+            - Two structural blanks: the inner array item of an array of arrays (it has no field name),
+              and the single top-level `objectarray` item of a `rows [ ]` mapping (the array output
+              structure — see the array's description). A child-bearing wrapper and a source-only row that
+              already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
+              name changes the output; it does not complete the row
 
             IMPORTANT: Do NOT use dot notation (e.g., "customer.firstName") in this field. Instead, create proper
             hierarchical structure with nested mappings:
@@ -12326,8 +12330,9 @@ components:
             }
             ```
 
-            When parsing existing mappings, empty 'generate' fields almost always indicate inner array structures
-            within a parent array.
+            When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+            empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
+            structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
           examples:
             - name
             - address
@@ -13308,6 +13313,12 @@ components:
         object-array row left with no source, no destination and no remaining child `mappings` or
         `buildArrayHelper` entries; a row with only one of the two, and a source-less, destination-less
         wrapper that still has children, are kept.
+
+        The shape of the array is the mapper's **JSON structure**. Named top-level items produce an object
+        record (`record { }`). Exactly one top-level item with `dataType: objectarray` and no `generate` is
+        the `rows [ ]` structure: the mapped record is an array — usually one element per element of the
+        source array that root's `buildArrayHelper` iterates — Handlebars templates such as `http.body`
+        bind it as `rows` instead of `record`, and the mapping editor shows that row's destination disabled.
       x-celigo-ai-guidance:
         - |-
           Rows that exist in the saved document — including `Draft` and `Inactive` rows and
@@ -13316,6 +13327,14 @@ components:
           them. Only a row with neither source nor destination — and, for an object or
           object-array row, no remaining children — can be left out; the save would drop it
           anyway. A wrapper with children but no `generate` is kept by the save, so keep it.
+        - |-
+          A single unnamed top-level `objectarray` item is the `rows [ ]` JSON structure, not a
+          missing destination: keep it unnamed when editing (naming it turns the output into an
+          object, and a template that iterates `rows` then renders nothing), and author that
+          shape only when the request body must be an array or a template iterates `rows`.
+          The editor's save check accepts the unnamed root only in the `rows [ ]` structure;
+          any other row with a source and no `generate` fails with "One or more destination
+          field values not entered".
       items:
         type: object
         properties:
@@ -13331,7 +13350,11 @@ components:
               - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
               - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
               - For array fields: Set to the array property name, then configure 'buildArrayHelper'
-              - For arrays within arrays: Leave EMPTY for the inner array mappings, as they don't have field names
+              - Two structural blanks: the inner array item of an array of arrays (it has no field name),
+                and the single top-level `objectarray` item of a `rows [ ]` mapping (the array output
+                structure — see the array's description). A child-bearing wrapper and a source-only row that
+                already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
+                name changes the output; it does not complete the row
 
               IMPORTANT: Do NOT use dot notation (e.g., "customer.firstName") in this field. Instead, create proper
               hierarchical structure with nested mappings:
@@ -13346,8 +13369,9 @@ components:
               }
               ```
 
-              When parsing existing mappings, empty 'generate' fields almost always indicate inner array structures
-              within a parent array.
+              When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+              empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
+              structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
             examples:
               - name
               - address

package/dist/import.yml

@@ -677,11 +677,11 @@ paths:
 
         The integrator.io UI never calls this path — the import editor's
         "Preview" and "Send" buttons both go through
-        `POST /v1/pageProcessors/preview`. This endpoint is the API-only,
-        unscoped counterpart to
-        `POST /v1/integrations/{_integrationId}/flows/{_flowId}/imports/preview`
-        — prefer this variant when previewing a standalone import that is not
-        yet associated with a flow.
+        `POST /v1/pageProcessors/preview`. This is the only import preview
+        route on the public API: unlike exports, imports have no flow-scoped
+        sibling — `POST /v1/integrations/{_integrationId}/flows/{_flowId}/imports/preview`
+        answers 404 `resource_not_found`. To preview an import inside its
+        flow, use `POST /v1/pageProcessors/preview`.
       requestBody:
         required: true
         content:
@@ -934,82 +934,6 @@ paths:
                         message: _connectionId is required.
         '401':
           $ref: '#/components/responses/401-unauthorized'
-  /v1/integrations/{_integrationId}/flows/{_flowId}/imports/preview:
-    post:
-      x-internal: false
-      summary: Preview import data
-      description: |
-        Runs the import pipeline — field mappings, transformations, and hooks —
-        against the supplied sample data and returns the per-record results.
-        Treat the preview as capable of executing the composed destination
-        request: its unscoped sibling (`POST /v1/imports/preview`) is verified
-        to write real records to live destinations and offers no option to
-        disable the send, so do not preview create/update imports against
-        production systems with data you do not want written. For a
-        compose-only preview of the destination request, use
-        `POST /v1/pageProcessors/preview` with `{preview: true}` on the
-        target entry.
-      operationId: previewImportData
-      tags:
-        - Imports
-      parameters:
-        - in: path
-          name: _integrationId
-          required: true
-          schema:
-            type: string
-            format: objectId
-            x-celigo-refModel: integrations
-            examples:
-              - 60a2c4e6f321d800129a1a3c
-          description: Integration ID
-        - in: path
-          name: _flowId
-          required: true
-          schema:
-            type: string
-            format: objectId
-            x-celigo-refModel: flows
-            examples:
-              - 64ff4b22612a134bd2f45538
-          description: Flow ID
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/PreviewRequest'
-            examples:
-              one_record:
-                summary: Preview an existing import against one sample record
-                value:
-                  _importId: 5f8d43a1b9e5a80011a35f2c
-                  sampleData:
-                    name: Acme Corp
-                    email: contact@acme.com
-      responses:
-        '200':
-          description: Successfully previewed import data
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/PreviewResponse'
-              examples:
-                mapped_record:
-                  summary: Mapped record as composed for the destination
-                  value:
-                    data:
-                      - name: Acme Corp
-                        email: contact@acme.com
-                    errors: []
-        '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'
   /v1/imports/{_id}/dependencies:
     get:
       x-internal: false
@@ -12363,7 +12287,11 @@ components:
             - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
             - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
             - For array fields: Set to the array property name, then configure 'buildArrayHelper'
-            - For arrays within arrays: Leave EMPTY for the inner array mappings, as they don't have field names
+            - Two structural blanks: the inner array item of an array of arrays (it has no field name),
+              and the single top-level `objectarray` item of a `rows [ ]` mapping (the array output
+              structure — see the array's description). A child-bearing wrapper and a source-only row that
+              already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
+              name changes the output; it does not complete the row
 
             IMPORTANT: Do NOT use dot notation (e.g., "customer.firstName") in this field. Instead, create proper
             hierarchical structure with nested mappings:
@@ -12378,8 +12306,9 @@ components:
             }
             ```
 
-            When parsing existing mappings, empty 'generate' fields almost always indicate inner array structures
-            within a parent array.
+            When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+            empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
+            structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
           examples:
             - name
             - address
@@ -13360,6 +13289,12 @@ components:
         object-array row left with no source, no destination and no remaining child `mappings` or
         `buildArrayHelper` entries; a row with only one of the two, and a source-less, destination-less
         wrapper that still has children, are kept.
+
+        The shape of the array is the mapper's **JSON structure**. Named top-level items produce an object
+        record (`record { }`). Exactly one top-level item with `dataType: objectarray` and no `generate` is
+        the `rows [ ]` structure: the mapped record is an array — usually one element per element of the
+        source array that root's `buildArrayHelper` iterates — Handlebars templates such as `http.body`
+        bind it as `rows` instead of `record`, and the mapping editor shows that row's destination disabled.
       x-celigo-ai-guidance:
         - |-
           Rows that exist in the saved document — including `Draft` and `Inactive` rows and
@@ -13368,6 +13303,14 @@ components:
           them. Only a row with neither source nor destination — and, for an object or
           object-array row, no remaining children — can be left out; the save would drop it
           anyway. A wrapper with children but no `generate` is kept by the save, so keep it.
+        - |-
+          A single unnamed top-level `objectarray` item is the `rows [ ]` JSON structure, not a
+          missing destination: keep it unnamed when editing (naming it turns the output into an
+          object, and a template that iterates `rows` then renders nothing), and author that
+          shape only when the request body must be an array or a template iterates `rows`.
+          The editor's save check accepts the unnamed root only in the `rows [ ]` structure;
+          any other row with a source and no `generate` fails with "One or more destination
+          field values not entered".
       items:
         type: object
         properties:
@@ -13383,7 +13326,11 @@ components:
               - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
               - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
               - For array fields: Set to the array property name, then configure 'buildArrayHelper'
-              - For arrays within arrays: Leave EMPTY for the inner array mappings, as they don't have field names
+              - Two structural blanks: the inner array item of an array of arrays (it has no field name),
+                and the single top-level `objectarray` item of a `rows [ ]` mapping (the array output
+                structure — see the array's description). A child-bearing wrapper and a source-only row that
+                already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
+                name changes the output; it does not complete the row
 
               IMPORTANT: Do NOT use dot notation (e.g., "customer.firstName") in this field. Instead, create proper
               hierarchical structure with nested mappings:
@@ -13398,8 +13345,9 @@ components:
               }
               ```
 
-              When parsing existing mappings, empty 'generate' fields almost always indicate inner array structures
-              within a parent array.
+              When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+              empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
+              structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
             examples:
               - name
               - address
@@ -16364,6 +16312,23 @@ components:
               per-mode contract.  Handlebars expressions in ``extract`` always
               reference ``{{record.field}}`` regardless — only JSONPath
               behavior flips with ``inputContext``.
+            - |-
+              ## JSON structure — record { } or rows [ ]
+
+              The shape of this array is the mapper's JSON structure. Named
+              top-level items produce an object record; ``http.body`` and the
+              other templates bind it as ``record``. Exactly one top-level item
+              with ``dataType: objectarray`` and no ``generate`` is the
+              ``rows [ ]`` structure: the mapped record is an array — one
+              element per element the item's ``buildArrayHelper`` iterates —
+              and templates bind it as ``rows`` (``{{#each rows}}``), with
+              ``record.*`` undefined. The mapping editor shows that row's
+              destination disabled; its save check accepts the unnamed root
+              only in the ``rows [ ]`` structure and fails any other row that
+              has a source and no ``generate`` with "One or more destination
+              field values not entered". Keep the root unnamed when editing a
+              ``rows [ ]`` mapping — naming it turns the output into an object
+              and a ``{{#each rows}}`` body renders nothing.
             - |-
               ## IMPORT-SPECIFIC BEHAVIOR
 
@@ -17081,13 +17046,11 @@ components:
     ImportPreviewResponse:
       type: object
       description: |-
-        Envelope returned by `POST /v1/imports/preview` (and the scoped
-        `/v1/integrations/{_integrationId}/flows/{_flowId}/imports/preview`
-        variant). Carries per-stage diagnostics alongside the sampled records
-        produced by running the supplied source data through the import's
-        mapping/transform/target pipeline. The target stage executes the
-        composed destination request — see the operation descriptions for the
-        write-safety warning.
+        Envelope returned by `POST /v1/imports/preview`. Carries per-stage
+        diagnostics alongside the sampled records produced by running the
+        supplied source data through the import's mapping/transform/target
+        pipeline. The target stage executes the composed destination request —
+        see the operation description for the write-safety warning.
       properties:
         data:
           type: array
@@ -17283,67 +17246,6 @@ components:
                 celigo_classname:
                   type: string
                   description: Internal engine class name for the result (e.g. `Celigo.integrator.mapping.model.MapToNetSuiteResult`).
-    PreviewRequest:
-      type: object
-      description: |
-        Request body for running sample data through an import's pipeline
-        (mappings, transformations, hooks). The preview can execute the
-        composed destination request — see the operation descriptions for the
-        write-safety warning.
-      properties:
-        _importId:
-          type: string
-          format: objectId
-          x-celigo-refModel: imports
-          description: The import to preview. Required when previewing within a flow.
-          examples:
-            - 5f8d43a1b9e5a80011a35f2c
-        sampleData:
-          description: |
-            Sample source record(s) to run through the import's mappings and transformations.
-            May be a single object or an array of objects depending on the adaptor.
-          oneOf:
-            - title: Single record
-              type: object
-              additionalProperties: true
-            - title: Array of records
-              type: array
-              items:
-                type: object
-                additionalProperties: true
-        options:
-          type: object
-          description: Optional overrides applied only for this preview.
-          additionalProperties: true
-      additionalProperties: true
-    PreviewResponse:
-      type: object
-      description: |
-        Result of running a preview against the configured import. Shows the
-        mapped/transformed records as composed for the destination.
-      properties:
-        data:
-          type: array
-          description: Mapped and transformed records produced by the import.
-          items:
-            type: object
-            additionalProperties: true
-        errors:
-          type: array
-          description: Any validation or transformation errors encountered while building the preview.
-          items:
-            type: object
-            properties:
-              code:
-                type: string
-                description: Machine-readable code identifying the type of preview error.
-              message:
-                type: string
-                description: Human-readable explanation of what went wrong while building the preview.
-              path:
-                type: string
-                description: Path to the field or configuration element the error relates to.
-      additionalProperties: true
     DependencyEntry:
       type: object
       description: A single resource that depends on the queried resource.

package/dist/tool.yml

@@ -1273,6 +1273,10 @@ paths:
         broader history. Use an entry's `executionId` with
         `GET /v1/tools/{_id}/invocations/{executionId}` to drill into its steps.
 
+        Entries are written asynchronously: a run appears here a few seconds after
+        `POST /v1/tools/{_id}/invoke` returns, so re-read before concluding that a run
+        was not logged.
+
         Sandbox Tools return `403`. Custom roles only see invocations whose
         `_invokerIntegrationId` is in their accessible integrations.
       parameters:
@@ -1288,7 +1292,9 @@ paths:
               - 65a98d1ef2b40000098c3a4d
         - name: pageSize
           in: query
-          description: Number of entries per page. Larger values are clamped to 100.
+          description: |-
+            Number of entries per page. Larger values are clamped to 100; `0` or a non-numeric
+            value returns `400` `invalid_url`.
           schema:
             type: integer
             minimum: 1
@@ -1454,7 +1460,11 @@ paths:
                       nextPageUrl: null
                       prevPageUrl: null
         '400':
-          description: Invalid query parameter, for example a `status` token outside the enum.
+          description: |-
+            Invalid query parameter: a `status` token outside the enum (`invalid_status`), a
+            `sortOrder` other than `asc`/`desc` (`invalid_sort_order`), a `time_gte`/`time_lte`
+            that is not a timestamp (`invalid_field`), or a `pageSize` below 1 or non-numeric
+            (`invalid_url`).
           content:
             application/json:
               schema:
@@ -1465,6 +1475,23 @@ paths:
                     errors:
                       - code: invalid_status
                         message: Status should be either success, error or ignore.
+                invalid_sort_order:
+                  value:
+                    errors:
+                      - code: invalid_sort_order
+                        message: Sort order should be either asc or desc.
+                invalid_time:
+                  summary: '`time_gte` is not a timestamp'
+                  value:
+                    errors:
+                      - code: invalid_field
+                        message: 'The value provided for the field: ''time_gte'' is invalid.'
+                invalid_page_size:
+                  summary: '`pageSize` is 0 or not a number'
+                  value:
+                    errors:
+                      - code: invalid_url
+                        message: pageSize is not valid.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
@@ -1506,14 +1533,16 @@ paths:
         - name: time_gte
           in: query
           required: true
-          description: Start of the deletion window. Omitting it returns `400` `invalid_query_params`.
+          description: |-
+            Start of the deletion window. Must be earlier than `time_lte`; omitting either bound
+            returns `400` `invalid_query_params`.
           schema:
             type: string
             format: date-time
         - name: time_lte
           in: query
           required: true
-          description: End of the deletion window. Must not be in the future.
+          description: End of the deletion window. Neither bound may be in the future.
           schema:
             type: string
             format: date-time
@@ -1521,7 +1550,9 @@ paths:
         '202':
           description: Deletion request accepted for asynchronous processing. No body.
         '400':
-          description: Missing or invalid window parameters.
+          description: |-
+            Missing or invalid window parameters — a bound is omitted, a bound is in the future,
+            or `time_gte` is not before `time_lte`. Nothing is deleted.
           content:
             application/json:
               schema:
@@ -1532,6 +1563,21 @@ paths:
                     errors:
                       - code: invalid_query_params
                         message: time_gte query parameter is required for deleting logs.
+                missing_time_lte:
+                  value:
+                    errors:
+                      - code: invalid_query_params
+                        message: time_lte query parameter is required for deleting logs.
+                future_window:
+                  value:
+                    errors:
+                      - code: invalid_query_params
+                        message: time_gte and time_lte cannot be in the future.
+                inverted_window:
+                  value:
+                    errors:
+                      - code: invalid_query_params
+                        message: time_gte must be before time_lte.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
@@ -1553,8 +1599,12 @@ paths:
         `recordId` with the log-data endpoint to read the payload it processed.
 
         When the invocation is missing or not visible under the caller's integration ACL,
-        the endpoint returns `204 No Content`. `404` applies only to an unknown or inaccessible
-        Tool `_id`. A malformed `executionId` returns `422`. Sandbox Tools return `403`.
+        the endpoint returns `204 No Content`. The trace is written asynchronously: for a few
+        seconds after `POST /v1/tools/{_id}/invoke` returns, a valid `invocationId` also answers
+        `204`, and the header can then appear before its step records, with an empty `steps`
+        array. Re-read before treating a run as unknown or as failed before its first step.
+        `404` applies only to an unknown or inaccessible Tool `_id`. A malformed `executionId`
+        returns `422`. Sandbox Tools return `403`.
       parameters:
         - name: _id
           in: path
@@ -1630,7 +1680,9 @@ paths:
                     logMode: debug
                     steps: []
         '204':
-          description: Invocation not found or not visible under the caller's integration ACL.
+          description: |-
+            Invocation not found, not visible under the caller's integration ACL, or not yet
+            written — a run answers `204` for a few seconds after the invoke returns.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '403':
@@ -1801,9 +1853,17 @@ paths:
         came out — selected by `_expOrImpId`, `stage`, `groupId`, and `recordId` from the
         trace-metadata response. The input and output bubbles store their payload under the
         `schemaValidation` stage; a lookup step stores the response it merged under
-        `responseMapping`. A selector that matches nothing returns `200` with an empty `logs`
-        array. Large payloads are not inlined — the entry carries an `externalReference` whose
-        `s3Key` you pass to the signed-URL endpoint.
+        `responseMapping`; a step that makes an outbound API call, such as an HTTP lookup,
+        stores each request it sent under `apiCall`, one entry per attempt, so a retried
+        request shows each failed attempt before the one that succeeded. Large payloads are
+        not inlined — the entry carries an `externalReference` whose `s3Key` you pass to the
+        signed-URL endpoint.
+
+        A selector that matches nothing returns `200` with an empty `logs` array — a stage
+        the step never ran for that record, a `groupId` from another step, and a step that
+        recorded no request all look the same. Payloads are written after the trace's step
+        records, so for a run that just finished an empty array can also mean the payload has
+        not landed yet; re-query before concluding nothing was stored.
 
         For nested Tools, set `stage` to `tool` with the nested ToolImport id to fetch the
         composed input/output payload.
@@ -1886,6 +1946,43 @@ paths:
                               orderId: SO-1043
                           errors: []
                     errors: []
+                apiCall:
+                  summary: HTTP lookup requests — a failed attempt, then the retry that succeeded
+                  value:
+                    logs:
+                      - log:
+                          apiCallTraceKeyId: M3bsB9KB
+                          stage: apiCall
+                          apiCallType: lookupexport
+                          status: failed
+                          request:
+                            method: GET
+                            uri: https://api.example.com/v1/orders
+                            headers:
+                              accept: application/json
+                              Authorization: Bearer ********
+                          response:
+                            statusCode: 503
+                            headers:
+                              content-type: text/html
+                            body: <html><head><title>503 Service Temporarily Unavailable</title></head></html>
+                      - log:
+                          apiCallTraceKeyId: cI09faBo
+                          stage: apiCall
+                          apiCallType: lookupexport
+                          status: success
+                          request:
+                            method: GET
+                            uri: https://api.example.com/v1/orders
+                            headers:
+                              accept: application/json
+                              Authorization: Bearer ********
+                          response:
+                            statusCode: 200
+                            headers:
+                              content-type: application/json; charset=utf-8
+                            body: '[{"_id":"6a50f177a8d85436a4a890db","name":"SO-1043"}]'
+                    errors: []
                 noMatch:
                   summary: Selector matched no stored payload
                   value:
@@ -3394,7 +3491,11 @@ components:
             - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
             - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
             - For array fields: Set to the array property name, then configure 'buildArrayHelper'
-            - For arrays within arrays: Leave EMPTY for the inner array mappings, as they don't have field names
+            - Two structural blanks: the inner array item of an array of arrays (it has no field name),
+              and the single top-level `objectarray` item of a `rows [ ]` mapping (the array output
+              structure — see the array's description). A child-bearing wrapper and a source-only row that
+              already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
+              name changes the output; it does not complete the row
 
             IMPORTANT: Do NOT use dot notation (e.g., "customer.firstName") in this field. Instead, create proper
             hierarchical structure with nested mappings:
@@ -3409,8 +3510,9 @@ components:
             }
             ```
 
-            When parsing existing mappings, empty 'generate' fields almost always indicate inner array structures
-            within a parent array.
+            When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+            empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
+            structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
           examples:
             - name
             - address
@@ -4391,6 +4493,12 @@ components:
         object-array row left with no source, no destination and no remaining child `mappings` or
         `buildArrayHelper` entries; a row with only one of the two, and a source-less, destination-less
         wrapper that still has children, are kept.
+
+        The shape of the array is the mapper's **JSON structure**. Named top-level items produce an object
+        record (`record { }`). Exactly one top-level item with `dataType: objectarray` and no `generate` is
+        the `rows [ ]` structure: the mapped record is an array — usually one element per element of the
+        source array that root's `buildArrayHelper` iterates — Handlebars templates such as `http.body`
+        bind it as `rows` instead of `record`, and the mapping editor shows that row's destination disabled.
       x-celigo-ai-guidance:
         - |-
           Rows that exist in the saved document — including `Draft` and `Inactive` rows and
@@ -4399,6 +4507,14 @@ components:
           them. Only a row with neither source nor destination — and, for an object or
           object-array row, no remaining children — can be left out; the save would drop it
           anyway. A wrapper with children but no `generate` is kept by the save, so keep it.
+        - |-
+          A single unnamed top-level `objectarray` item is the `rows [ ]` JSON structure, not a
+          missing destination: keep it unnamed when editing (naming it turns the output into an
+          object, and a template that iterates `rows` then renders nothing), and author that
+          shape only when the request body must be an array or a template iterates `rows`.
+          The editor's save check accepts the unnamed root only in the `rows [ ]` structure;
+          any other row with a source and no `generate` fails with "One or more destination
+          field values not entered".
       items:
         type: object
         properties:
@@ -4414,7 +4530,11 @@ components:
               - For regular fields: Set to the exact property name (e.g., "firstName", "price", "isActive")
               - For object fields: Set to the object property name, then add child mappings in the 'mappings' array
               - For array fields: Set to the array property name, then configure 'buildArrayHelper'
-              - For arrays within arrays: Leave EMPTY for the inner array mappings, as they don't have field names
+              - Two structural blanks: the inner array item of an array of arrays (it has no field name),
+                and the single top-level `objectarray` item of a `rows [ ]` mapping (the array output
+                structure — see the array's description). A child-bearing wrapper and a source-only row that
+                already exist in a saved document also stay unnamed when the tree is re-sent — filling in a
+                name changes the output; it does not complete the row
 
               IMPORTANT: Do NOT use dot notation (e.g., "customer.firstName") in this field. Instead, create proper
               hierarchical structure with nested mappings:
@@ -4429,8 +4549,9 @@ components:
               }
               ```
 
-              When parsing existing mappings, empty 'generate' fields almost always indicate inner array structures
-              within a parent array.
+              When parsing existing mappings, an empty `generate` inside a parent array is an inner array; an
+              empty `generate` on the ONLY top-level item, with `dataType: objectarray`, is the `rows [ ]` JSON
+              structure — array output, bound as `rows` in templates — and is intentional, not a missing name.
             examples:
               - name
               - address
@@ -24981,6 +25102,23 @@ components:
               per-mode contract.  Handlebars expressions in ``extract`` always
               reference ``{{record.field}}`` regardless — only JSONPath
               behavior flips with ``inputContext``.
+            - |-
+              ## JSON structure — record { } or rows [ ]
+
+              The shape of this array is the mapper's JSON structure. Named
+              top-level items produce an object record; ``http.body`` and the
+              other templates bind it as ``record``. Exactly one top-level item
+              with ``dataType: objectarray`` and no ``generate`` is the
+              ``rows [ ]`` structure: the mapped record is an array — one
+              element per element the item's ``buildArrayHelper`` iterates —
+              and templates bind it as ``rows`` (``{{#each rows}}``), with
+              ``record.*`` undefined. The mapping editor shows that row's
+              destination disabled; its save check accepts the unnamed root
+              only in the ``rows [ ]`` structure and fails any other row that
+              has a source and no ``generate`` with "One or more destination
+              field values not entered". Keep the root unnamed when editing a
+              ``rows [ ]`` mapping — naming it turns the output into an object
+              and a ``{{#each rows}}`` body renders nothing.
             - |-
               ## IMPORT-SPECIFIC BEHAVIOR
 
@@ -37273,7 +37411,10 @@ components:
             - '2026-09-22T03:27:29.411000Z'
         timeTaken:
           type: integer
-          description: Total processing time in milliseconds.
+          description: |-
+            Wall-clock duration of the invocation in milliseconds, from request to response.
+            It also counts time spent outside the steps, so it exceeds the sum of the step
+            `timeTaken` values on the trace.
           examples:
             - 1025
         logMode:
@@ -37446,7 +37587,10 @@ components:
             - '2026-09-22T03:27:29.411000Z'
         timeTaken:
           type: integer
-          description: Total processing time in milliseconds.
+          description: |-
+            Wall-clock duration of the invocation in milliseconds, from request to response.
+            It also counts time spent outside the steps, so it exceeds the sum of the step
+            `timeTaken` values — use the step sum when apportioning time across steps.
           examples:
             - 1025
         traceKey:
@@ -37492,7 +37636,8 @@ components:
           type: array
           description: |-
             Step records in execution order — input bubble, branch steps, output bubble.
-            Empty when the run failed before its first step.
+            Empty when the run failed before its first step. Step records are written after
+            the header, so a run read seconds after it finished can also return an empty array.
           items:
             $ref: '#/components/schemas/ToolInvocationStep'
     ToolChildrenResponse:
@@ -37544,10 +37689,14 @@ components:
           description: |-
             Processing stage whose payload to fetch. The input and output bubbles store their
             payload under `schemaValidation`; a lookup step stores the merged response under
-            `responseMapping`; use `tool` for a nested ToolImport's composed payload.
+            `responseMapping`; a step that makes an outbound API call, such as an HTTP lookup,
+            stores each request it sent under `apiCall`; use `tool` for a nested ToolImport's
+            composed payload. A stage the step never ran for this record returns an empty
+            `logs` array, the same as a record that stored nothing.
           examples:
             - schemaValidation
             - responseMapping
+            - apiCall
             - tool
         groupId:
           type: string
@@ -37573,12 +37722,19 @@ components:
             Small payloads are inlined under `log`; a large payload is replaced by an
             `externalReference[]` whose `source.s3Key` you pass to
             `GET /v1/tools/{_id}/invocations/{executionId}/logs/signedURL` to download it.
+            A bubble or mapping stage returns one entry per record; the `apiCall` stage
+            returns one entry per request the step sent, in order, so a retried request shows
+            each failed attempt before the one that succeeded.
           items:
             type: object
             properties:
               log:
                 type: object
-                description: Inlined payload for the selected record and stage.
+                description: |-
+                  Inlined payload for the selected record and stage. Record-level stages such
+                  as `schemaValidation` and `responseMapping` carry the timestamp, selector echo
+                  and `input` / `output` / `errors`; the `apiCall` stage carries the request sent
+                  and the response received instead.
                 properties:
                   timestamp:
                     type: string
@@ -37628,6 +37784,71 @@ components:
                     items:
                       type: object
                       additionalProperties: true
+                  apiCallTraceKeyId:
+                    type: string
+                    description: Identifier of one request attempt. Present when `stage` is `apiCall`.
+                    examples:
+                      - M3bsB9KB
+                  apiCallType:
+                    type: string
+                    description: Kind of step that sent the request, such as a lookup export. Present when `stage` is `apiCall`.
+                    examples:
+                      - lookupexport
+                  status:
+                    type: string
+                    enum:
+                      - success
+                      - failed
+                    x-enumDescriptions:
+                      success: The attempt received a response the step accepted
+                      failed: The attempt was rejected or errored; a later entry may carry the retry
+                    description: Outcome of this request attempt. Present when `stage` is `apiCall`.
+                  request:
+                    type: object
+                    description: |-
+                      The request the step sent on this attempt — `method`, `uri` and `headers`.
+                      Credential headers are masked. Present when `stage` is `apiCall`.
+                    properties:
+                      method:
+                        type: string
+                        description: HTTP method of the attempt.
+                      uri:
+                        type: string
+                        description: Full URL the attempt called.
+                      headers:
+                        type: object
+                        additionalProperties: true
+                        description: Request headers as sent, with credential values masked.
+                    additionalProperties: true
+                  response:
+                    type: object
+                    description: |-
+                      The response this attempt received — `statusCode`, `headers`, and the raw
+                      `body` as a string when the endpoint sent one. Present when `stage` is
+                      `apiCall`.
+                    properties:
+                      statusCode:
+                        type: integer
+                        description: HTTP status the endpoint returned.
+                      headers:
+                        type: object
+                        additionalProperties: true
+                        description: Response headers as received.
+                      body:
+                        type: string
+                        description: Raw response body; JSON arrives as a serialized string.
+                    additionalProperties: true
+                if:
+                  properties:
+                    stage:
+                      const: apiCall
+                  required:
+                    - stage
+                then:
+                  required:
+                    - status
+                    - request
+                    - response
                 additionalProperties: true
               externalReference:
                 type: array

package/package.json

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

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "5a3e9e39",
+		"iasCommit": "f7df0c08",
 		"generatedAt": "2026-10-12"
 	},
 	"roots": {