@celigo/api-specs 0.2.99 → 0.2.101

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/api.yml

@@ -1685,6 +1685,10 @@ paths:
         `runId` is the parent `flowJob._id`.
 
         Test-run invocations do **not** surface in `GET /v1/apis/{_id}/logs`.
+
+        Test runs never paginate, whatever `pagination.enabled` says: the captured success
+        response carries no `pagination` object, and a `Celigo-Next-Cursor` entry in
+        `mockRequest.headers` is not validated — a malformed value does not fail the run.
       parameters:
         - name: _id
           in: path
@@ -3527,7 +3531,8 @@ components:
             Callers fetch the next page by resending the request unchanged with
             the cursor in the `Celigo-Next-Cursor` request header — for every
             HTTP method; a `next_cursor` field in the request body is ordinary
-            payload, not a cursor. Cursor faults fail the invocation with `400`:
+            payload, not a cursor. Resending a cursor returns the same page again.
+            Cursor faults fail the invocation with `400`:
             `invalid_cursor_format`, `cursor_signature_invalid` (the cursor was
             altered), `cursor_version_unsupported`, `cursor_api_mismatch` (the
             cursor was issued by a different API), `cursor_filter_mismatch` (the
@@ -3536,7 +3541,19 @@ components:
             pagination is off). Cursors expire and are then rejected with `410
             cursor_expired`; a response hook that turns the mapped body into a
             non-object fails with `422 api_pagination_response_not_object`.
-            Absent from responses until set.
+
+            Saving the volume-driver export — even with no changes — invalidates
+            every cursor issued so far: the next call with one returns `200` with
+            an empty final page, `{"pagination": {"has_more": false}}`, as if the
+            source were exhausted; restart from the first page without a cursor.
+            Saving the API document itself leaves issued cursors valid.
+            A success response whose `statusCode` is `204` returns no body, so the
+            `pagination` object and cursor are lost with it — a paginated API
+            needs a body-bearing success status.
+
+            Absent from responses until set. A PUT that omits `pagination` keeps
+            the stored value; send `{"enabled": null}` to clear it (the field is
+            then absent again).
           x-celigo-ai-guidance:
             - |-
               When calling a paginated API, read `pagination.next_cursor` from the
@@ -3544,7 +3561,11 @@ components:
               the identical path, query string, and body; putting it in the body
               returns the first page again, and adding or changing a query
               parameter fails with 400 `cursor_filter_mismatch`. Loop until
-              `has_more` is false — the final page carries no `next_cursor`.
+              `has_more` is false — the final page carries no `next_cursor`. Saving
+              the volume-driver export mid-walk ends the walk early without an
+              error: the next cursor call returns an empty
+              `{"pagination": {"has_more": false}}` page, so restart from the first
+              page after any save of that export.
             - |-
               Script-mode APIs never paginate: POST and PUT silently drop
               `pagination` (it never reads back), and `PATCH /pagination/enabled`
@@ -3560,9 +3581,15 @@ components:
                 with source paging configured; otherwise the write fails with
                 `422` `api_pagination_no_volume_driver` (no lookup at all),
                 `api_pagination_adapter_not_supported` (any other adaptor), or
-                `api_pagination_source_not_paged` (lookup without paging). When
-                false, a `Celigo-Next-Cursor` header is rejected with `400
-                cursor_not_supported_for_api`.
+                `api_pagination_source_not_paged` (lookup without paging). The
+                same check repeats on every later save of the API and at every
+                invocation while the stored value is true: if the volume driver
+                loses its paging afterwards (the export save itself succeeds),
+                every call fails with `400 api_pagination_source_not_paged` and
+                every PUT or PATCH of the API — including one that omits
+                `pagination` — is refused with the `422` until paging is restored
+                or this flag is set to false. When false, a `Celigo-Next-Cursor`
+                header is rejected with `400 cursor_not_supported_for_api`.
               examples:
                 - true
               x-celigo-ai-guidance:
@@ -3573,6 +3600,13 @@ components:
                   webhook, or other non-HTTP/Salesforce/NetSuite lookup with 422
                   `api_pagination_adapter_not_supported`, and an API with no lookup
                   with 422 `api_pagination_no_volume_driver`.
+                - |-
+                  Before removing paging from the volume-driver export of an API
+                  whose `enabled` is true, PATCH `/pagination/enabled` to false
+                  first (that PATCH succeeds even while the lookup is unpaged).
+                  Otherwise the export save returns 200 but every call to the API
+                  fails 400 `api_pagination_source_not_paged` and every save of
+                  the API fails 422 with the same code.
         script:
           $ref: '#/components/schemas/Script'
         builder:

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

@@ -6558,7 +6558,10 @@ components:
                 - '{"records": [{"id": "{{record.id}}", "exported": true}]}'
         paging:
           type: object
-          description: Controls how the export requests subsequent pages when the API returns multi-page responses. The `method` field determines which companion fields are required and how each next page is requested. For the page, skip, and token methods, reference the matching pagination variable (`{{export.http.paging.page}}`, `{{export.http.paging.skip}}`, or `{{export.http.paging.token}}`) in the relative URI or request body — misconfigured pagination is a common cause of incomplete data retrieval.
+          description: |-
+            Controls how the export requests subsequent pages when the API returns multi-page responses. The `method` field determines which companion fields are required and how each next page is requested. For the page, skip, and token methods, reference the matching pagination variable (`{{export.http.paging.page}}`, `{{export.http.paging.skip}}`, or `{{export.http.paging.token}}`) in the relative URI or request body — misconfigured pagination is a common cause of incomplete data retrieval.
+
+            When this export is the first lookup of a builder-mode API with `pagination.enabled` set, it is that API's volume driver: saving the export (even unchanged) invalidates the API's issued cursors, so a caller mid-walk gets an empty final page, and removing `paging` is accepted on save but makes every call to the API fail with `400 api_pagination_source_not_paged` until paging is restored or the API's flag is turned off.
           x-celigo-ai-guidance:
             - Configuration object for navigating through multi-page API responses.
             - |-
@@ -12308,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:
@@ -12323,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
@@ -13305,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
@@ -13313,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:
@@ -13328,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:
@@ -13343,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/flow.yml

@@ -1006,12 +1006,13 @@ paths:
         collection-level endpoint used by the UI's "move to section" action — it updates multiple flows in a
         single call rather than requiring a per-flow `PUT /v1/flows/{_id}` with a modified `_flowGroupingId`.
 
-        The flows referenced in `_flowIds` must all belong to the same integration as the target
-        `_flowGroupingId`. Pass `_flowGroupingId: null` (or an empty string, depending on platform version)
-        to remove the flows from their current group back to the integration's default section.
+        Every flow in `_flowIds` must belong to the same integration, and `_flowGroupingId` must be one
+        of that integration's `flowGroupings` — a grouping that does not exist or belongs to another
+        integration is rejected with 400 `flowgrouping_update_error`. Pass `_flowGroupingId: null` or
+        omit it to move the flows back to the integration's default (Unassigned) section.
 
-        Flow groupings are managed on the parent integration (`PUT /v1/integrations/{_id}` with a
-        modified `flowGroupings[]` array) — create the group first, then call this to populate it.
+        Flow groupings are managed on the parent integration (`PUT` or `PATCH /v1/integrations/{_id}`
+        with a modified `flowGroupings[]` array) — create the group first, then call this to populate it.
       requestBody:
         required: true
         content:
@@ -1035,10 +1036,37 @@ paths:
       responses:
         '204':
           description: |-
-            Flows reassigned. Empty response body. The server does not validate the grouping id —
-            nonexistent `_flowGroupingId` values are also accepted with 204.
+            Flows reassigned. Empty response body. Flow ids that match no flow in the account are
+            silently skipped, so an unknown `_flowIds` entry (or an empty list) also answers 204.
         '400':
-          $ref: '#/components/responses/400-bad-request'
+          description: |-
+            The request was rejected: the flows span more than one integration (`invalid_request`),
+            the grouping is not one of the flows' integration's `flowGroupings`
+            (`flowgrouping_update_error`), or an id is not a well-formed ObjectId (`invalid_ref` —
+            an empty-string `_flowGroupingId` fails this way; use `null` to ungroup).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                differentIntegrations:
+                  summary: Flows belong to different integrations
+                  value:
+                    errors:
+                      - code: invalid_request
+                        message: Unable to update flows for flowgrouping, since flows belongs to different integrations.
+                groupingNotInIntegration:
+                  summary: Grouping does not exist or belongs to another integration
+                  value:
+                    errors:
+                      - code: flowgrouping_update_error
+                        message: 'Failed to update flow grouping for flow: Order sync. Error: Sorry, Failed to link flowGroupingId. FlowGrouping does not belong to Integration: 6ac1ef49fa3e52974f433c1b.'
+                malformedGroupingId:
+                  summary: Grouping id is not an ObjectId (including an empty string)
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _flowGroupingId.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
@@ -5513,10 +5541,12 @@ components:
           format: objectId
           description: |-
             Flow grouping for organizing related flows in the UI. References an entry in the
-            integration's `flowGroupings` array (not a standalone collection); invalid ids are
-            silently dropped by the server. At runtime the flow's steps read the referenced
-            group's `settings` under the fixed scope key `flowGrouping` (e.g.
-            `{{settings.flowGrouping.<fieldId>}}`).
+            integration's `flowGroupings` array (not a standalone collection); an id that is not
+            one of the flow's own integration's groupings — nonexistent, or a grouping of another
+            integration — fails POST and PUT with 422 `flowgrouping_not_belong`. Omit it or pass
+            `null` to leave the flow in the integration's default section. At runtime the flow's
+            steps read the referenced group's `settings` under the fixed scope key `flowGrouping`
+            (e.g. `{{settings.flowGrouping.<fieldId>}}`).
           examples:
             - 60a2c4e6f321d800129a1a3c
         _keepDeltaBehindFlowId:
@@ -6170,7 +6200,9 @@ components:
       properties:
         _flowIds:
           type: array
-          description: The flows to move. All must belong to the same integration as the target flow group.
+          description: |-
+            The flows to move. All must belong to the same integration as the target flow group
+            (400 `invalid_request` otherwise); ids that match no flow are silently skipped.
           minItems: 1
           items:
             type: string
@@ -6180,13 +6212,14 @@ components:
           type:
             - string
             - 'null'
+          format: objectId
           description: |-
-            Id of the flow group (within the integration's `flowGroupings[]`). Pass `null` (or an empty
-            string, depending on platform version) to remove the flows from their current group back to the
-            integration's default section.
+            Grouping within the integration's `flowGroupings[]` to move the flows into. Must belong to
+            the flows' own integration (400 `flowgrouping_update_error` otherwise). Pass `null` or omit
+            it to move the flows back to the integration's default section; an empty string is rejected
+            with 400 `invalid_ref`.
       required:
         - _flowIds
-        - _flowGroupingId
     FlowStepError:
       type: object
       description: |-