@celigo/api-specs 0.2.70 → 0.2.71

package/dist/api.yml

@@ -144,7 +144,9 @@ paths:
       description: |-
         Creates a new API. For `script` mode, include `script._scriptId` and `script.function` (the
         server also copies these to the top level in the response). For `builder` mode,
-        `builder.request` is required (at minimum `relativeURI` and `method`).
+        `builder.request` can be added later — an API created without it has no route until
+        `relativeURI` and `method` are set — but when it is present it must carry both, or the
+        request fails with 422 `invalid_api_builder_request`.
 
         Builder-mode APIs are created with `logging: {"mode": "basic"}` when the account license
         has logging enabled -- the request body cannot override this (`logging` is ignored on POST
@@ -666,7 +668,13 @@ paths:
       summary: Update the grouping for one or more APIs
       description: |-
         Assigns or removes an API grouping for the specified API resources. Pass
-        `_apiGroupingId: null` to ungroup. Nonexistent API IDs are silently accepted.
+        `_apiGroupingId: null` or omit it to ungroup. Nonexistent API IDs are silently accepted.
+
+        Every API in `_apiIds` must belong to the same integration, and the grouping must be
+        one of that integration's `apiGroupings`. Each API is re-saved through full validation,
+        so an API that cannot be saved as it stands (for example a builder API whose response
+        router is not configured yet) fails the request with 400 `apigrouping_update_error`;
+        regroup such an API with a full `PUT /v1/apis/{_id}` instead.
       requestBody:
         required: true
         content:
@@ -704,7 +712,34 @@ paths:
         '204':
           description: API grouping updated successfully (no body returned).
         '400':
-          $ref: '#/components/responses/400-bad-request'
+          description: |-
+            The request was rejected: the APIs span more than one integration
+            (`invalid_request`), or one API could not be re-saved with the new grouping
+            (`apigrouping_update_error` — the grouping belongs to another integration, or the
+            API fails its own validation).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                differentIntegrations:
+                  summary: APIs belong to different integrations
+                  value:
+                    errors:
+                      - code: invalid_request
+                        message: Unable to update apis for apigrouping, since apis belongs to different integrations.
+                groupingNotInIntegration:
+                  summary: Grouping belongs to another integration
+                  value:
+                    errors:
+                      - code: apigrouping_update_error
+                        message: 'Failed to update api grouping for api: Get Customer. Error: API grouping does not belong to Integration: 6a429af50547257e3301246c.'
+                apiFailsValidation:
+                  summary: API cannot be re-saved as it stands
+                  value:
+                    errors:
+                      - code: apigrouping_update_error
+                        message: 'Failed to update api grouping for api: Get Customer. Error: Response router id must be "apiRouter"..'
         '401':
           $ref: '#/components/responses/401-unauthorized'
   /v1/apis/{_id}/logs:
@@ -2119,7 +2154,8 @@ paths:
         combination of `version`, `method`, and `relativeURI` must be unique. Reusing all
         three returns a 422 `clone_api_already_exists`. Pass `_integrationId` to create the
         clone inside an integration — when omitted, the clone is created standalone rather
-        than inheriting the source API's integration.
+        than inheriting the source API's integration. Add `_apiGroupingId` to file the clone
+        under one of that integration's `apiGroupings`.
 
         Only **builder-type** APIs can be cloned — cloning any other API type returns a 400
         `clone_not_supported`.
@@ -2168,12 +2204,32 @@ paths:
                     standalone — it does not inherit the source API's integration.
                   examples:
                     - 6a429af50547257e3301246c
+                _apiGroupingId:
+                  type:
+                    - string
+                    - 'null'
+                  format: objectId
+                  description: |-
+                    Grouping inside the target integration that the clone is filed under; `null`
+                    or omitted leaves it ungrouped. Honored only together with `_integrationId` —
+                    sent without it, the clone is created standalone and the grouping is dropped
+                    silently. A grouping that belongs to a different integration fails the clone
+                    with 422 `apigrouping_not_belong` and nothing is created.
+                  examples:
+                    - 60a1b2c3d4e5f60012345678
             examples:
               default:
                 summary: Clone to a new version
                 value:
                   version: v2
                   name: IDP (v2)
+              intoGroup:
+                summary: Clone into an integration's API grouping
+                value:
+                  version: v2
+                  name: IDP (v2)
+                  _integrationId: 6a429af50547257e3301246c
+                  _apiGroupingId: 60a1b2c3d4e5f60012345678
       responses:
         '201':
           description: |-
@@ -2234,8 +2290,9 @@ paths:
           $ref: '#/components/responses/404-not-found'
         '422':
           description: |-
-            An API with the same `version`, `method`, and `relativeURI` already exists. Clone
-            with a different `version` (or change the method/URI) to create a distinct API.
+            An API with the same `version`, `method`, and `relativeURI` already exists — clone
+            with a different `version` (or change the method/URI) to create a distinct API — or
+            `_apiGroupingId` is not one of the target integration's `apiGroupings`.
           content:
             application/json:
               schema:
@@ -2246,6 +2303,13 @@ paths:
                     errors:
                       - code: clone_api_already_exists
                         message: The clone API already exists with the same version, method and relative uri.
+                groupingNotInIntegration:
+                  summary: Grouping belongs to a different integration
+                  value:
+                    errors:
+                      - field: _apiGroupingId
+                        code: apigrouping_not_belong
+                        message: 'Failed to create Api for _id "68ae4264b5f755d2dd3796b4" due to: API grouping does not belong to Integration: 6a429af50547257e3301246c'
   /v1/apis/{_id}/clone/validate:
     post:
       x-internal: false
@@ -3332,6 +3396,15 @@ components:
             API. On reads the field is omitted when unset, never `null`.
           examples:
             - 60a1b2c3d4e5f60012345678
+          x-celigo-ai-guidance:
+            - |-
+              The id must be one of the `apiGroupings` of the integration named by _integrationId
+              in the same write; any other id fails with 422 `apigrouping_not_belong` — including
+              a PUT that changes _integrationId but keeps the previous grouping. When moving an
+              API, send the target integration's grouping or `null` (Unassigned).
+            - |-
+              `PATCH /v1/apis/{_id}` rejects `/_apiGroupingId` (422, not a whitelisted property);
+              regroup with a full PUT or with `PUT /v1/apis/updateApiGrouping`.
         description:
           type: string
           description: Optional description of the API's purpose.
@@ -3678,11 +3751,13 @@ components:
       description: |-
         Request body for creating or updating an API.
 
-        For builder-mode APIs, populate the `builder` object (at minimum
-        `builder.request.relativeURI` and `builder.request.method`); the `script`
-        field is ignored. For script-mode APIs, populate `script` with `_scriptId`
-        and `function`; the `builder` field is ignored. On PUT, send the complete
-        object — omitted fields revert to defaults.
+        For builder-mode APIs, populate the `builder` object; the `script` field is
+        ignored. `builder.request` can be omitted on create — the API has no route
+        until `relativeURI` and `method` are set — but when it is present it must
+        carry both, or the write fails with 422 `invalid_api_builder_request`. For
+        script-mode APIs, populate `script` with `_scriptId` and `function`; the
+        `builder` field is ignored. On PUT, send the complete object — omitted
+        fields revert to defaults.
 
         Set `type` explicitly to `builder` or `script`. The server infers `script`
         when `type` is omitted, but new APIs must declare it.

package/dist/integration.yml

@@ -287,7 +287,9 @@ paths:
         | `/flowGroupings` | Flow grouping configuration |
         | `/apiGroupings` | API grouping configuration |
 
-        All other paths are rejected with `422`.
+        All other paths are rejected with `422`. A successful patch returns no body, so the
+        server-assigned `_id` of a grouping added through `/flowGroupings` or `/apiGroupings`
+        is only available from a follow-up `GET`.
       operationId: patchIntegration
       tags:
         - Integrations
@@ -4088,7 +4090,19 @@ components:
 
             Used to group APIs into named sections with their own settings/settingsForm.
             Works identically to `flowGroupings` but for API resources. Create groupings here,
-            then assign APIs to them via `PUT /v1/apis/updateApiGrouping`.
+            then assign APIs to them via `PUT /v1/apis/updateApiGrouping`. A grouping that still
+            has member APIs survives being removed from this array — ungroup its APIs first.
+          x-celigo-ai-guidance:
+            - |-
+              `Unassigned` is a reserved name (422 `invalid_apigrouping_name`) and names must be
+              unique within the integration (422 `duplicate_field`).
+            - |-
+              Removing a grouping that still has member APIs returns success but leaves the
+              grouping in place; move those APIs with `PUT /v1/apis/updateApiGrouping` 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.70",
+  "version": "0.2.71",
   "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": "d5da91d",
+		"iasCommit": "de043a7",
 		"generatedAt": "2026-10-02"
 	},
 	"roots": {