docs: sampling

api/api.yaml

@@ -1077,6 +1077,16 @@ paths:
           schema:
             type: string
           example: "113e9685-9a51-42cc-8662-9d9725b17f14"
+        - name: skipSampling
+          in: query
+          required: false
+          description:
+            When `true`, skips the sample read that validates the installation's
+            read configuration against the provider before saving. Defaults to
+            `false`.
+          schema:
+            type: boolean
+            default: false
       requestBody:
         content:
           application/json:
@@ -1173,7 +1183,10 @@ paths:
               schema:
                 $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
         422:
-          description: Unprocessable Entity
+          description:
+            Unprocessable Entity. Returned when the config is invalid, or when the
+            sample read fails because a selected field or mapping is not visible to
+            the connected user. 
           content:
             application/problem+json:
               schema:
@@ -1341,6 +1354,16 @@ paths:
           schema:
             type: string
           example: 7b3c9d2e-5a1f-4e8b-b6d4-9c8a2f1e5d3b
+        - name: skipSampling
+          in: query
+          required: false
+          description:
+            When `true`, skips the sample read that validates the installation's
+            read configuration against the provider before saving. Defaults to
+            `false`.
+          schema:
+            type: boolean
+            default: false
       requestBody:
         content:
           application/json:
@@ -1423,6 +1446,15 @@ paths:
             application/problem+json:
               schema:
                 $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
+        422:
+          description:
+            Unprocessable Entity. Returned when the config is invalid, or when the
+            sample read fails because a selected field or mapping is not visible to
+            the connected user. 
+          content:
+            application/problem+json:
+              schema:
+                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
         default:
           description: Error
           content: