@celigo/api-specs 0.2.103 → 0.2.104

package/dist/enduser.yml

@@ -4726,11 +4726,12 @@ components:
           - `database` — required for every type EXCEPT `oracle` (uses `serviceName`)
             and `bigquery` (uses `bigquery.dataset`).
           - `user` — required for every type EXCEPT `bigquery`, `redshift`, and
-            `mssql` with `mssql.authType=azure-service-principal`.
+            `mssql` / `azuresynapse` with `mssql.authType=azure-service-principal`.
           - `password` — required when no SSL cert material is provided AND the
-            type is NOT `bigquery`, `redshift`, `snowflake`, or `mssql` with
-            `azure-service-principal` auth. When SSL cert material IS provided
-            without a password, both `ssl.key` and `ssl.cert` become required.
+            type is NOT `bigquery`, `redshift`, `snowflake`, or `mssql` /
+            `azuresynapse` with `azure-service-principal` auth. When SSL cert
+            material IS provided without a password, both `ssl.key` and `ssl.cert`
+            become required.
           - **Snowflake** — additionally requires `snowflake.warehouse` and
             `snowflake.authType`. When `snowflake.authType=keyPair`, also
             requires the `key` field at the rdbms level (the RSA private key).
@@ -4746,8 +4747,14 @@ components:
             iClient holding the role ARN) plus exactly one of
             `redshift.clusterIdentifier` (provisioned cluster) or
             `redshift.workgroupName` (Redshift Serverless).
-          - **MSSQL with `mssql.authType=azure-service-principal`** — requires
-            `_iClientId` (service principal credentials live in the iClient).
+          - **MSSQL / Azure Synapse with `mssql.authType=azure-service-principal`**
+            — requires `_iClientId` referencing an `azureserviceprincipal` iClient
+            (the Microsoft Entra tenant id, client id and client secret or
+            certificate live in the iClient); `user` and `password` are not used.
+            `_iClientId` with `basic` auth is rejected. Both types share the
+            `mssql` sub-object; `azuresynapse` is cloud-only, and the SQL Server
+            connection form offers service-principal auth in Cloud mode only — it
+            saves `basic` for an on-premise connection (`_agentId` set).
           - **Oracle** — runs in agent mode only, so requires `_agentId` on the
             parent connection object. Uses `serviceName` instead of `database`.
             Optionally also takes `serverType` and `instanceName`.
@@ -4840,8 +4847,10 @@ components:
         user:
           type: string
           description: |
-            Database username for authentication.
-            Required for all types except BigQuery (which uses service account auth).
+            Database username for authentication. Required for all types except
+            BigQuery (service account auth), Redshift, and `mssql` / `azuresynapse`
+            with `mssql.authType=azure-service-principal`, where the Entra principal
+            in the iClient signs in and a `user` sent anyway is stored unused.
           examples:
             - integration_user
         password:
@@ -4968,8 +4977,11 @@ components:
                 - keyPair
         mssql:
           type: object
-          description: |
-            Microsoft SQL Server / Azure Synapse-specific configuration.
+          description: |-
+            Microsoft SQL Server / Azure Synapse-specific configuration. Read for
+            both the `mssql` and the `azuresynapse` types — Azure Synapse
+            Analytics shares SQL Server's authentication model and this
+            sub-object.
           properties:
             authType:
               type: string
@@ -4977,14 +4989,30 @@ components:
                 - basic
                 - azure-service-principal
               x-enumDescriptions:
-                basic: Standard SQL Server authentication with username and password.
-                azure-service-principal: Azure Active Directory service principal authentication via iClient.
+                basic: Database user — SQL authentication with `user` and `password`
+                azure-service-principal: Microsoft Entra service principal held in the `azureserviceprincipal` iClient referenced by `_iClientId`; `user` and `password` are not used
               description: |-
-                Authentication type for MS SQL Server. Defaults to basic (username/password).
-                Use azure-service-principal for Azure AD service principal auth via an iClient.
+                How a Microsoft SQL Server or Azure Synapse connection
+                authenticates. Defaults to `basic` when omitted (the connection
+                form's "Database user"). With `azure-service-principal` the
+                connection signs in as the Entra application registered in the
+                iClient — a client secret, or on SQL Server a certificate — and
+                `_iClientId` must reference it. The SQL Server connection form
+                offers `azure-service-principal` in Cloud mode only and saves
+                `basic` for an on-premise connection (`_agentId` set).
               default: basic
               examples:
                 - basic
+              x-celigo-ai-guidance:
+                - |-
+                  With azure-service-principal, omit user and password: the API does not reject them —
+                  it stores them unused on the connection (live-verified 201 with both present), while
+                  the connection form removes them on save. Set them only for basic.
+                - |-
+                  A certificate-method azureserviceprincipal iClient is offered by the form on Microsoft
+                  SQL Server connections only; the Azure Synapse form's picker lists client-secret
+                  iClients. The API accepts either on either type (live-verified 201), so follow the
+                  form: bind a certificate iClient to mssql connections only.
         bigquery:
           type: object
           description: |
@@ -5165,10 +5193,13 @@ components:
           x-celigo-refModel: iclients
           description: |-
             Reference to an iClient holding auth credentials, stored inside the
-            rdbms object. Required when type is `mssql` and `mssql.authType` is
-            `azure-service-principal` (Azure service-principal credentials), and
-            when type is `redshift` and `redshift.authType` is `awsIam` (an
-            `awsIam`-provider iClient holding the role ARN to assume). For
+            rdbms object. Required when type is `mssql` or `azuresynapse` and
+            `mssql.authType` is `azure-service-principal` (an
+            `azureserviceprincipal` iClient — the Microsoft Entra tenant id,
+            client id and client secret or certificate), and when type is
+            `redshift` and `redshift.authType` is `awsIam` (an `awsIam`-provider
+            iClient holding the role ARN to assume). On `mssql` / `azuresynapse`
+            it is rejected when `mssql.authType` is `basic` or omitted. For
             Redshift the iClient must carry `awsIam.roleArn`, and that role's name
             must start with `celigo-data-warehouse-adaptor-` — the data-warehouse
             service assumes only roles in that family, so a role created for an S3
@@ -5176,6 +5207,18 @@ components:
           examples:
             - 66a1b2c3d4e5f60718293a4b
           x-celigo-ai-guidance:
+            - |-
+              For a mssql or azuresynapse connection with mssql.authType "azure-service-principal",
+              _iClientId is required (otherwise 422 missing_required_field on rdbms._iClientId
+              "Expected field: _iClientId to be present.") and must reference an azureserviceprincipal
+              iClient (otherwise 422 invalid_field on rdbms._iClientId "IClient provider must be
+              azureserviceprincipal for Service Principal authentication."). The same iClient can back
+              Azure Data Lake Storage Gen2, SQL Server and Synapse connections.
+            - |-
+              With mssql.authType "basic" (or omitted) on mssql / azuresynapse, do not set _iClientId:
+              422 invalid_field on rdbms._iClientId "The _iClientId field should not be set when using
+              basic authentication. Remove _iClientId or switch to azure-service-principal
+              authentication."
             - |-
               For a Redshift connection with redshift.authType "awsIam", the referenced iClient must
               have awsIam.roleArn set (otherwise 422 missing_required_field on rdbms._iClientId
@@ -5195,7 +5238,6 @@ components:
               - mysql
               - postgresql
               - mariadb
-              - azuresynapse
         required:
           - type
       then:
@@ -5239,120 +5281,149 @@ components:
           if:
             properties:
               type:
-                const: snowflake
+                const: azuresynapse
             required:
               - type
           then:
-            required:
-              - host
-              - database
-              - user
-            properties:
-              snowflake:
-                required:
-                  - authType
-                  - warehouse
             if:
               properties:
-                snowflake:
+                mssql:
                   properties:
                     authType:
-                      const: keyPair
+                      const: azure-service-principal
                   required:
                     - authType
               required:
-                - snowflake
+                - mssql
             then:
               required:
-                - key
+                - host
+                - database
+                - _iClientId
             else:
               required:
+                - host
+                - database
+                - user
                 - password
           else:
             if:
               properties:
                 type:
-                  const: oracle
+                  const: snowflake
               required:
                 - type
             then:
               required:
                 - host
+                - database
                 - user
-                - password
+              properties:
+                snowflake:
+                  required:
+                    - authType
+                    - warehouse
+              if:
+                properties:
+                  snowflake:
+                    properties:
+                      authType:
+                        const: keyPair
+                    required:
+                      - authType
+                required:
+                  - snowflake
+              then:
+                required:
+                  - key
+              else:
+                required:
+                  - password
             else:
               if:
                 properties:
                   type:
-                    const: bigquery
+                    const: oracle
                 required:
                   - type
               then:
                 required:
-                  - bigquery
-                properties:
-                  bigquery:
-                    required:
-                      - projectId
-                      - dataset
-                      - clientEmail
-                      - privateKey
+                  - host
+                  - user
+                  - password
               else:
                 if:
                   properties:
                     type:
-                      const: redshift
+                      const: bigquery
                   required:
                     - type
                 then:
                   required:
-                    - database
-                    - user
-                    - redshift
+                    - bigquery
                   properties:
-                    redshift:
+                    bigquery:
                       required:
-                        - region
+                        - projectId
+                        - dataset
+                        - clientEmail
+                        - privateKey
+                else:
                   if:
-                    required:
-                      - redshift
                     properties:
-                      redshift:
-                        required:
-                          - authType
-                        properties:
-                          authType:
-                            const: awsIam
+                      type:
+                        const: redshift
+                    required:
+                      - type
                   then:
                     required:
-                      - _iClientId
-                    properties:
-                      redshift:
-                        oneOf:
-                          - required:
-                              - clusterIdentifier
-                            not:
-                              required:
-                                - workgroupName
-                          - required:
-                              - workgroupName
-                            not:
-                              required:
-                                - clusterIdentifier
-                  else:
+                      - database
+                      - user
+                      - redshift
                     properties:
                       redshift:
                         required:
-                          - aws
-                          - clusterIdentifier
-                        not:
+                          - region
+                    if:
+                      required:
+                        - redshift
+                      properties:
+                        redshift:
                           required:
-                            - workgroupName
-                        properties:
-                          aws:
+                            - authType
+                          properties:
+                            authType:
+                              const: awsIam
+                    then:
+                      required:
+                        - _iClientId
+                      properties:
+                        redshift:
+                          oneOf:
+                            - required:
+                                - clusterIdentifier
+                              not:
+                                required:
+                                  - workgroupName
+                            - required:
+                                - workgroupName
+                              not:
+                                required:
+                                  - clusterIdentifier
+                    else:
+                      properties:
+                        redshift:
+                          required:
+                            - aws
+                            - clusterIdentifier
+                          not:
                             required:
-                              - accessKeyId
-                              - secretAccessKey
+                              - workgroupName
+                          properties:
+                            aws:
+                              required:
+                                - accessKeyId
+                                - secretAccessKey
     MongoDB:
       type: object
       description: |-

package/dist/filestorage.yml

@@ -156,8 +156,29 @@ paths:
             examples:
               - 683b2a0e1c3d5f001a9e8b03
       responses:
-        '204':
-          description: Multipart upload aborted and the pending item removed.
+        '200':
+          description: |-
+            Multipart upload aborted and the pending item removed. Returns the
+            removed item's `_id` and `name`; canceling it again answers 404
+            `STORAGE_ITEM_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - _id
+                  - name
+                properties:
+                  _id:
+                    type: string
+                    format: objectId
+                    description: ID of the canceled item.
+                  name:
+                    type: string
+                    description: Name of the canceled item.
+              example:
+                _id: 683b2a0e1c3d5f001a9e8b03
+                name: database-export.sql
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
@@ -2415,9 +2436,11 @@ components:
           type: integer
           minimum: 1
           description: |-
-            Total number of parts the file will be split into. Required when
-            uploadType is multipart; the response returns presigned URLs for as
-            many parts as the part budget allows.
+            Required when uploadType is multipart. On a new upload, the total number
+            of parts the file will be split into; the response returns presigned URLs
+            for as many parts as the part budget allows. On a resume (`_id`,
+            `uploadId`, and `issuedPartsCount` set), the number of further part URLs
+            to issue, numbered on from `issuedPartsCount`.
           examples:
             - 50
         uploadId:

package/dist/iclient.yml

@@ -321,7 +321,10 @@ paths:
         Replaces an iClient. All mutable fields must be provided — omitted
         fields are reset to defaults. Secrets returned as `"******"` can be
         sent back as-is to keep the existing value, except a Google service
-        account: every update must include the full JSON key.
+        account: every update must include the full JSON key. An Azure
+        service principal keeps its stored `clientSecret` or `certificate`
+        when the field is omitted — only a new value replaces it, and
+        `certificate` is never returned.
       operationId: updateIClient
       tags:
         - iClients
@@ -639,7 +642,7 @@ components:
             netsuite: NetSuite token-based authentication.
             amazonmws: Amazon Marketplace Web Service (MWS) authentication.
             awsIam: AWS IAM cross-account role authentication (assume-role with an external ID).
-            azureserviceprincipal: Azure AD service principal (client credentials) authentication.
+            azureserviceprincipal: Microsoft Entra service principal (client secret or certificate) for Azure Data Lake Storage Gen2, Microsoft SQL Server and Azure Synapse connections
             googleserviceaccount: Google Cloud service-account key authentication (JSON key file).
             integrator: Celigo integrator.io internal authentication.
             salesforce: Salesforce OAuth 2.0 authentication.
@@ -3933,8 +3936,12 @@ components:
         azureserviceprincipal:
           type: object
           description: |-
-            Azure AD service principal credentials. Required when `provider`
-            is `azureserviceprincipal`.
+            Microsoft Entra (Azure AD) service principal credentials. Required
+            when `provider` is `azureserviceprincipal`. One iClient of this
+            provider can back Azure Data Lake Storage Gen2, Microsoft SQL Server
+            (cloud) and Azure Synapse Analytics connections; the connection forms
+            offer the certificate method from Microsoft SQL Server connections
+            only.
           required:
             - clientId
             - tenantId
@@ -3951,7 +3958,15 @@ components:
               description: |-
                 Which credential the service principal presents. Defaults to
                 `client-secret` when omitted. Each method rejects the other
-                method's credential fields on save.
+                method's credential fields on save. Changing the method on an
+                update replaces the credential: send the new method's credential
+                and drop the old one.
+              x-celigo-ai-guidance:
+                - |-
+                  Under authMethod "certificate", a clientSecret is rejected with 422 invalid_field_value
+                  on azureserviceprincipal.clientSecret "Client secret is not used when auth method is
+                  certificate."; a missing certificate with 422 missing_required_field on
+                  azureserviceprincipal.certificate "Expected field: certificate to be present."
             clientId:
               type: string
               description: Azure AD application (client) ID.
@@ -3962,24 +3977,35 @@ components:
               description: |-
                 Azure AD client secret. Required when `authMethod` is
                 `client-secret` (or omitted). Returned masked as `"******"`.
-                Re-send that value on update to keep it; it is not preserved if omitted.
+                On update the stored secret is kept when the field is omitted or
+                re-sent as the mask; only a new value replaces it.
             certificate:
               type: string
+              writeOnly: true
               description: |-
                 PEM bundle (certificate + private key) for certificate auth.
                 Required when `authMethod` is `certificate`; rejected under
-                `client-secret`. Maximum 20 KiB of PEM text. Returned masked.
+                `client-secret`. Maximum 20 KiB of PEM text. Never returned in
+                responses, not even masked. On update the stored PEM is kept when
+                the field is omitted; only a new value replaces it.
               x-celigo-ai-guidance:
                 - |-
                   If the PEM's private key is encrypted (BEGIN ENCRYPTED PRIVATE
-                  KEY / Proc-Type 4,ENCRYPTED), certificatePassword is required;
+                  KEY / Proc-Type 4,ENCRYPTED), certificatePassword is required
+                  (422 invalid_field_value on azureserviceprincipal.certificatePassword "This
+                  certificate's private key is encrypted. Enter the client certificate password.");
                   if it is unencrypted, sending certificatePassword is rejected.
+                - |-
+                  The save does not check that the PEM is a usable credential — a placeholder PEM
+                  carrying the BEGIN CERTIFICATE and BEGIN PRIVATE KEY blocks saves (live-verified
+                  201). Enter the real PEM in the iClient editor before testing a connection that
+                  uses the iClient.
             certificatePassword:
               type: string
               description: |-
                 Passphrase for an encrypted private key inside `certificate`.
                 Required exactly when the PEM's key is encrypted; rejected when
-                it is not. Maximum 256 bytes. Returned masked.
+                it is not. Maximum 256 bytes. Returned masked when set.
             tenantId:
               type: string
               description: Azure AD tenant (directory) ID.
@@ -4332,10 +4358,13 @@ components:
         For `custom_oauth2`, credentials go in the `oauth2` sub-object.
         Secrets (`clientSecret`, `privateKey`, and so on) come back masked
         as `"******"`. Re-send that mask on update to keep the stored
-        secret; omitting it does not. A Google service account is the
-        exception: `serviceAccountJSON` is not returned, and every update
-        must send the full key — the mask or an omission fails with 422
-        `invalid_json_key`.
+        secret; omitting it does not. Two providers differ. A Google
+        service account: `serviceAccountJSON` is not returned, and every
+        update must send the full key — the mask or an omission fails with
+        422 `invalid_json_key`. An Azure service principal: the stored
+        `clientSecret` or `certificate` is kept when its field is omitted
+        on update, and only a new value replaces it (`certificate` is never
+        returned, not even masked).
       required:
         - provider
       allOf:

package/dist/lookupcache.yml

@@ -605,7 +605,7 @@ paths:
                         value: New York
                       - key: ZZ
                         error:
-                          message: Key not found
+                          message: The requested key does not match any entry in the lookup cache. Check the key.
         '400':
           $ref: '#/components/responses/400-bad-request'
         '401':
@@ -1169,7 +1169,7 @@ components:
               type: string
               description: Human-readable explanation of the miss.
               examples:
-                - Key not found
+                - The requested key does not match any entry in the lookup cache. Check the key.
     LookupCacheDataReadResponse:
       type: object
       description: |-