@celigo/api-specs 0.2.99 → 0.2.100

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

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: |-

package/dist/integration.yml

@@ -365,8 +365,8 @@ paths:
       x-internal: false
       summary: Clone an integration
       description: |
-        Creates a copy of an existing integration.
-        Supports optionally remapping referenced connections (via connectionMap).
+        Creates a copy of an existing integration. When the source has registered
+        connections, remap each one via `connectionMap`; mapped connections are reused, not cloned.
       operationId: cloneIntegration
       tags:
         - Integrations
@@ -382,7 +382,7 @@ paths:
             examples:
               - 69680d7111d1437fbcbce534
       requestBody:
-        required: false
+        required: true
         content:
           application/json:
             schema:
@@ -397,8 +397,8 @@ paths:
                     626168f90b6ef816b50c82d7: 64a1234567890abcdef12345
                     6553ebdeda62bb22e7fa81ff: 64a1234567890abcdef12346
       responses:
-        '200':
-          description: Integration cloned successfully
+        '201':
+          description: Integration cloned successfully. Returns a manifest of the resources the clone created.
           content:
             application/json:
               schema:
@@ -4063,7 +4063,10 @@ components:
           description: |-
             UI grouping configuration that groups an integration's flows into named
             sections. Works on ANY integration — this is NOT an Integration-App-only
-            feature; a plain integration can define flow groupings too.
+            feature; a plain integration can define flow groupings too. Create groupings
+            here, then assign flows to them via `PUT /v1/flows/updateFlowGrouping`. A
+            grouping that still has member flows survives being removed from this array —
+            ungroup its flows first.
 
             Omit unless you are explicitly configuring flow grouping behavior.
           x-celigo-ai-guidance:
@@ -4071,6 +4074,17 @@ components:
               Set this ONLY when the user explicitly asks to group flows into named sections (e.g.
               "create the integration with flow groups Order Intake and Fulfillment").
               Otherwise omit it — do not synthesize groupings the user did not ask for.
+            - |-
+              `Unassigned` is a reserved name (422 `invalid_flowgrouping_name`) and names and `_id`s
+              must be unique within the integration (422 `duplicate_field`) — on POST, PUT and PATCH
+              alike.
+            - |-
+              Removing a grouping that still has member flows returns success but leaves the
+              grouping in place; move those flows with `PUT /v1/flows/updateFlowGrouping` first.
+            - |-
+              `POST` and `PUT` answer with the saved integration, so a new grouping's `_id` is
+              in the response; `PATCH` answers `204` with no body, so after a patch the `_id`
+              comes from a follow-up `GET`.
           items:
             type: object
             additionalProperties: true
@@ -4478,11 +4492,11 @@ components:
       type: object
       description: Request body for cloning an integration.
       required:
-        - connectionMap
+        - name
       properties:
         name:
           type: string
-          description: Name for the cloned integration. If omitted, the server generates "Clone - <original name>".
+          description: Name for the cloned integration.
           examples:
             - Clone - Integration 1
         description:
@@ -4506,6 +4520,9 @@ components:
             Mapping of original connection _ids to replacement connection _ids.
             Keys are source connection _ids on the original integration; values
             are target connection _ids in the destination environment.
+            Required when the source integration has registered connections — omitting it or
+            sending an empty map fails with 400 `invalid_connectionMap`. Map a connection to
+            itself to reuse it in the clone; omit the map when the source has none.
           additionalProperties:
             type: string
           example:

package/dist/tool.yml

@@ -710,14 +710,26 @@ paths:
         - Tools
       summary: Clone a tool
       description: |-
-        Creates a copy of a tool in the target integration and returns a manifest of the
-        resources the clone created. The clone records its lineage in `_sourceId`, which
-        places it in the source tool's clone family.
+        Creates a copy of a tool in the target integration, together with the export and
+        import steps it references, and returns a manifest of the resources the clone
+        created. The clone records its lineage in `_sourceId`, which places it in the source
+        tool's clone family.
 
         The target integration is never inferred from the source tool — pass the source
-        tool's own integration id to clone in place.
+        tool's own integration id to clone in place. When any step of the tool references a
+        connection, `connectionMap` is required as well: every connection the tool uses must
+        appear as a key, mapped to itself to reuse it or to another connection of the account
+        to repoint the cloned steps. A tool with no connection-bearing steps clones without it.
 
-        Use `GET /v1/tools/{_id}/clone/preview` first to see what the clone would create.
+        Use `GET /v1/tools/{_id}/clone/preview` first to see what the clone would create —
+        each `Connection` object in the preview is a key `connectionMap` must carry.
+      x-celigo-ai-guidance:
+        - |-
+          Build `connectionMap` from the clone preview: one key per `Connection` object it lists,
+          each mapped to its own id unless the user asked to repoint the clone. Omitting the map
+          (or sending `{}`) when a step references a connection fails with 400
+          `invalid_connectionMap`; a key the tool does not reference, or a value that is not a
+          connection in the account, fails with 422 `invalid_connectionId` and nothing is created.
       parameters:
         - name: _id
           in: path
@@ -750,15 +762,37 @@ paths:
                   description: Name for the cloned tool. Defaults to `Clone - <source tool name>` when omitted.
                   examples:
                     - Customer enrichment tool (copy)
+                connectionMap:
+                  type: object
+                  description: |-
+                    Connection ids the tool's steps reference, each mapped to the connection the
+                    cloned steps use instead. Required when any step references a connection —
+                    omitted or empty, the clone fails with 400 `invalid_connectionMap`. Map an id
+                    to itself to keep the connection; every key must be a connection the tool
+                    references and every value a connection in the account.
+                  additionalProperties:
+                    type: string
+                    format: objectId
+                  examples:
+                    - 6ac1ef4a38b24d95ffac2545: 6ac1ef4a38b24d95ffac2545
             examples:
               default:
-                summary: Clone into the same integration
+                summary: Clone a tool with no connection-bearing steps into the same integration
                 value:
                   _integrationId: 6a429af50547257e3301246c
                   name: Customer enrichment tool (copy)
+              with_connection_map:
+                summary: Clone a tool whose lookup step uses a connection, reusing that connection
+                value:
+                  _integrationId: 6a429af50547257e3301246c
+                  name: Customer enrichment tool (copy)
+                  connectionMap:
+                    6ac1ef4a38b24d95ffac2545: 6ac1ef4a38b24d95ffac2545
       responses:
         '201':
-          description: The clone was created. Returns a manifest of the resources the clone created.
+          description: |-
+            The clone was created. Returns a manifest of every resource the clone created —
+            the new tool plus the export and import steps it copied.
           content:
             application/json:
               schema:
@@ -769,7 +803,7 @@ paths:
                   properties:
                     model:
                       type: string
-                      description: Model name of the created resource (e.g. `Tool`).
+                      description: Model name of the created resource (e.g. `Tool`, `Export`, `Import`).
                       examples:
                         - Tool
                     _id:
@@ -780,12 +814,22 @@ paths:
                         - 6a869d2f3ae8ccee42a45c44
               examples:
                 default:
-                  summary: Clone created a tool
+                  summary: Clone created a tool with no steps
                   value:
                     - model: Tool
                       _id: 6a869d2f3ae8ccee42a45c44
+                with_steps:
+                  summary: Clone created a tool and the lookup export it references
+                  value:
+                    - model: Export
+                      _id: 6ac1ef8a38b24d95ffac2d64
+                    - model: Tool
+                      _id: 6ac1ef8a38b24d95ffac2d78
         '400':
-          description: The body omits `_integrationId` (`required_field_missing`).
+          description: |-
+            The body omits `_integrationId` (`required_field_missing`), or the tool's steps
+            reference a connection and `connectionMap` is missing or empty
+            (`invalid_connectionMap`).
           content:
             application/json:
               schema:
@@ -797,10 +841,40 @@ paths:
                     errors:
                       - code: required_field_missing
                         message: 'required field: _integrationId is missing'
+                missingConnectionMap:
+                  summary: A step references a connection but no connectionMap was sent
+                  value:
+                    errors:
+                      - code: invalid_connectionMap
+                        message: The resource which you are trying to create requires a connectionMap.
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
           $ref: '#/components/responses/404-not-found'
+        '422':
+          description: |-
+            `connectionMap` does not match the tool: a value is not a connection in the account,
+            or a key is not a connection the tool's steps reference (the unmapped connection is
+            reported alongside). Nothing is created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                unknownTargetConnection:
+                  summary: A mapped value is not a connection in the account
+                  value:
+                    errors:
+                      - code: invalid_connectionId
+                        message: 'The _connectionId provided for the key ''6ac1ef4a38b24d95ffac2545'': ''000000000000000000000001'' is invalid.'
+                keyNotReferenced:
+                  summary: A key is not one of the tool's connections, so the real one is unmapped
+                  value:
+                    errors:
+                      - code: invalid_connectionId
+                        message: The key '000000000000000000000001' in connectionMap doesn't match with any of the _id's of the connection documents.
+                      - code: invalid_connectionId
+                        message: 'The _connectionId provided for the key ''6ac1ef4a38b24d95ffac2545'': '''' is invalid.'
   /v1/tools/{_id}/clone/preview:
     get:
       x-internal: false
@@ -30365,7 +30439,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.
             - |-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.99",
+  "version": "0.2.100",
   "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": "6feafe65",
+		"iasCommit": "5a3e9e39",
 		"generatedAt": "2026-10-12"
 	},
 	"roots": {