Address review feedback on Knowledge endpoint docs

Narrow the tag applied_at/applied_by null case to content removals, say that
the detach admin_id is checked but not recorded, document the missing internal
article errors, add the content search 401 scope example, note values returned
as strings, and add request_id and per_page to a few examples.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Author: cathalging

descriptions/0/api.intercom.io.yaml

@@ -5736,7 +5736,7 @@ paths:
         Requires the `read_articles_scope` or `read_write_articles_scope` OAuth scope.
       responses:
         '200':
-          description: successful
+          description: successful. `pages.page` and `pages.per_page` are returned as strings when you send `page` and `per_page` in the request, and as integers otherwise.
           content:
             application/json:
               examples:
@@ -5817,7 +5817,26 @@ paths:
               schema:
                 "$ref": "#/components/schemas/internal_article"
         '400':
-          description: Bad request. The request body is empty.
+          description: Bad request. The request body is empty, in which case the response has no body, or `audience_ids` is not an array of integers
+          content:
+            application/json:
+              examples:
+                audience_ids is not an array:
+                  value:
+                    type: error.list
+                    request_id: null
+                    errors:
+                    - code: data_invalid
+                      message: audience_ids must be an array
+                audience_ids contains a non-integer:
+                  value:
+                    type: error.list
+                    request_id: null
+                    errors:
+                    - code: data_invalid
+                      message: audience_ids must contain only integer values
+              schema:
+                "$ref": "#/components/schemas/error"
         '404':
           description: Teammate, folder or audience ID not found
           content:
@@ -5847,7 +5866,7 @@ paths:
               schema:
                 "$ref": "#/components/schemas/error"
         '422':
-          description: Missing required parameters, or body_markdown sent with body or json_blocks
+          description: Missing required parameters, body_markdown sent with body or json_blocks, or an ai_*_availability value that is not a boolean
           content:
             application/json:
               examples:
@@ -5865,6 +5884,13 @@ paths:
                     errors:
                     - code: parameter_invalid
                       message: body_markdown is mutually exclusive with body and json_blocks - please provide only one
+                Non-boolean availability flag:
+                  value:
+                    type: error.list
+                    request_id: null
+                    errors:
+                    - code: parameter_invalid
+                      message: ai_chatbot_availability must be a boolean (true or false)
               schema:
                 "$ref": "#/components/schemas/error"
         '401':
@@ -6042,9 +6068,28 @@ paths:
               schema:
                 "$ref": "#/components/schemas/internal_article"
         '400':
-          description: Bad request. The request body is empty.
+          description: Bad request. The request body is empty, in which case the response has no body, or `audience_ids` is not an array of integers
+          content:
+            application/json:
+              examples:
+                audience_ids is not an array:
+                  value:
+                    type: error.list
+                    request_id: null
+                    errors:
+                    - code: data_invalid
+                      message: audience_ids must be an array
+                audience_ids contains a non-integer:
+                  value:
+                    type: error.list
+                    request_id: null
+                    errors:
+                    - code: data_invalid
+                      message: audience_ids must contain only integer values
+              schema:
+                "$ref": "#/components/schemas/error"
         '404':
-          description: Internal article, folder or audience ID not found
+          description: Internal article, teammate, folder or audience ID not found
           content:
             application/json:
               examples:
@@ -6055,6 +6100,13 @@ paths:
                     errors:
                     - code: not_found
                       message: Resource not found
+                Teammate not found:
+                  value:
+                    type: error.list
+                    request_id: null
+                    errors:
+                    - code: parameter_invalid
+                      message: Admin with ID 999999 not found
                 Folder not found:
                   value:
                     type: error.list
@@ -6072,7 +6124,7 @@ paths:
               schema:
                 "$ref": "#/components/schemas/error"
         '422':
-          description: body_markdown sent with body or json_blocks, or the article is in a release running a live experiment
+          description: body_markdown sent with body or json_blocks, an ai_*_availability value that is not a boolean, or the article is in a release running a live experiment
           content:
             application/json:
               examples:
@@ -6083,6 +6135,13 @@ paths:
                     errors:
                     - code: parameter_invalid
                       message: body_markdown is mutually exclusive with body and json_blocks - please provide only one
+                Non-boolean availability flag:
+                  value:
+                    type: error.list
+                    request_id: null
+                    errors:
+                    - code: parameter_invalid
+                      message: ai_chatbot_availability must be a boolean (true or false)
                 Release live experiment conflict:
                   value:
                     type: error.list
@@ -6350,8 +6409,9 @@ paths:
       - name: admin_id
         in: query
         required: false
-        description: Optional id of the teammate to attribute the removal to. Defaults
-          to the authenticating teammate.
+        description: Optional id of a teammate. The id is checked, and an unknown
+          teammate returns a 404 `admin_not_found` error, but the removal is not
+          recorded against the teammate.
         example: '1234'
         schema:
           type: string
@@ -6567,7 +6627,7 @@ paths:
         Requires the `read_articles_scope` or `read_write_articles_scope` OAuth scope.
       responses:
         '200':
-          description: successful
+          description: successful. `pages.page` and `pages.per_page` are returned as strings when you send `page` and `per_page` in the request, and as integers otherwise.
           content:
             application/json:
               example:
@@ -14428,7 +14488,26 @@ paths:
               schema:
                 "$ref": "#/components/schemas/error"
         '401':
-          $ref: "#/components/responses/Unauthorized"
+          description: Unauthorized. The token is invalid or is missing the `read_content` OAuth scope
+          content:
+            application/json:
+              examples:
+                Unauthorized:
+                  value:
+                    type: error.list
+                    request_id: 12a938a3-314e-4939-b773-5cd45738bd21
+                    errors:
+                    - code: unauthorized
+                      message: Access Token Invalid
+                Token lacks required scope:
+                  value:
+                    type: error.list
+                    request_id: a3e5b8e2-1234-5678-9abc-def012345678
+                    errors:
+                    - code: token_unauthorized
+                      message: Not authorized to access resource
+              schema:
+                "$ref": "#/components/schemas/error"
         '422':
           description: Invalid filter value
           content:
@@ -14601,12 +14680,14 @@ paths:
                 Invalid availability flag:
                   value:
                     type: error.list
+                    request_id: 7c1d9e2a-3b4f-4a56-8d70-1e2f3a4b5c6d
                     errors:
                     - code: parameter_invalid
                       message: ai_chatbot_availability must be a boolean
                 Malformed audience_ids:
                   value:
                     type: error.list
+                    request_id: 9a8b7c6d-5e4f-4321-b0a9-8f7e6d5c4b3a
                     errors:
                     - code: data_invalid
                       message: audience_ids must be an array
@@ -14641,6 +14722,7 @@ paths:
                 Unknown audience IDs:
                   value:
                     type: error.list
+                    request_id: 2b3c4d5e-6f70-4812-93a4-b5c6d7e8f901
                     errors:
                     - code: parameter_invalid
                       message: 'audience_ids contains unknown audience IDs: 999'
@@ -14661,6 +14743,7 @@ paths:
                 Body and JSON blocks both provided:
                   value:
                     type: error.list
+                    request_id: 4d5e6f70-8192-4a3b-8c4d-5e6f708192a3
                     errors:
                     - code: parameter_invalid
                       message: body_markdown and json_blocks are mutually exclusive - please provide only one
@@ -14824,12 +14907,14 @@ paths:
                 Invalid availability flag:
                   value:
                     type: error.list
+                    request_id: 6f708192-a3b4-4c5d-9e6f-708192a3b4c5
                     errors:
                     - code: parameter_invalid
                       message: ai_chatbot_availability must be a boolean
                 Malformed audience_ids:
                   value:
                     type: error.list
+                    request_id: 8192a3b4-c5d6-4e7f-8091-a2b3c4d5e6f7
                     errors:
                     - code: data_invalid
                       message: audience_ids must be an array
@@ -14871,6 +14956,7 @@ paths:
                 Unknown audience IDs:
                   value:
                     type: error.list
+                    request_id: a3b4c5d6-e7f8-4091-a2b3-c4d5e6f70819
                     errors:
                     - code: parameter_invalid
                       message: 'audience_ids contains unknown audience IDs: 999'
@@ -14891,6 +14977,7 @@ paths:
                 Body and JSON blocks both provided:
                   value:
                     type: error.list
+                    request_id: c5d6e7f8-0912-4a3b-b4c5-d6e7f8091a2b
                     errors:
                     - code: parameter_invalid
                       message: body_markdown and json_blocks are mutually exclusive - please provide only one
@@ -15124,8 +15211,9 @@ paths:
       - name: admin_id
         in: query
         required: false
-        description: Optional id of the teammate to attribute the removal to. Defaults
-          to the authenticating teammate.
+        description: Optional id of a teammate. The id is checked, and an unknown
+          teammate returns a 404 `admin_not_found` error, but the removal is not
+          recorded against the teammate.
         example: '1234'
         schema:
           type: string
@@ -38761,13 +38849,13 @@ components:
               format: uri
               description: A link to the next page of results. Omitted when on the
                 last page.
-              example: https://api.intercom.io/content/search?query=billing&page=2
+              example: https://api.intercom.io/content/search?query=billing&per_page=10&page=2
             prev:
               type: string
               format: uri
               description: A link to the previous page of results. Omitted when on
                 the first page.
-              example: https://api.intercom.io/content/search?query=billing&page=1
+              example: https://api.intercom.io/content/search?query=billing&per_page=10&page=1
         data:
           type: array
           description: The list of matched content items. Each item's `type`
@@ -38819,7 +38907,8 @@ components:
           example: en
         json_blocks:
           type: array
-          description: The content blocks that make up the body of the snippet.
+          description: The content blocks that make up the body of the snippet. In
+            responses, the blocks are returned as a JSON-encoded string rather than as an array.
           items:
             type: object
           example: