elastic · yctercero · Apr 24, 2026 · Apr 22, 2026 · Apr 22, 2026 · Apr 22, 2026
diff --git a/src/platform/packages/private/kbn-validate-oas/src/oas_error_baseline.json b/src/platform/packages/private/kbn-validate-oas/src/oas_error_baseline.json
@@ -1,4 +1,4 @@
 {
-  "./oas_docs/output/kibana.yaml": 554,
-  "./oas_docs/output/kibana.serverless.yaml": 519
+  "./oas_docs/output/kibana.yaml": 462,
+  "./oas_docs/output/kibana.serverless.yaml": 455
 }
@@ -54,6 +54,16 @@ paths:
                 - name
                 - description
                 - type
+            examples:
+              createDetection:
+                value:
+                  list_id: simple_list
+                  type: detection
+                  name: Sample Detection Exception List
+                  description: This is a sample detection type exception list.
+                  namespace_type: single
+                  tags: [malware]
+                  os_types: [linux]
       responses:
         200:
           description: Successful response

@@ -33,6 +33,21 @@ paths:
                 - $ref: '#/components/schemas/CreateExceptionListItemBlocklistWindows'
                 - $ref: '#/components/schemas/CreateExceptionListItemBlocklistLinux'
                 - $ref: '#/components/schemas/CreateExceptionListItemBlocklistMac'
+            examples:
+              simpleItem:
+                value:
+                  list_id: simple_list
+                  item_id: simple_list_item
+                  name: Sample Exception List Item
+                  type: simple
+                  description: This is a sample detection type exception item.
+                  namespace_type: single
+                  entries:
+                    - type: exists
+                      field: actingProcess.file.signer
+                      operator: excluded
+                  os_types: [linux]
+                  tags: [malware]
       responses:
         200:
           description: Successful response

@@ -51,6 +51,26 @@ paths:
                     namespace_type: single
                     os_types: [linux]
                     tags: [malware]
+            examples:
+              addItems:
+                value:
+                  items:
+                    - item_id: simple_list_item
+                      list_id: simple_list
+                      type: simple
+                      name: Sample Exception List Item
+                      description: This is a sample detection type exception item.
+                      entries:
+                        - type: exists
+                          field: actingProcess.file.signer
+                          operator: excluded
+                        - type: match_any
+                          field: host.name
+                          value: [saturn, jupiter]
+                          operator: included
+                      namespace_type: single
+                      os_types: [linux]
+                      tags: [malware]
       responses:
         200:
           description: Successful response

@@ -33,6 +33,11 @@ export const DeleteExceptionListRequestQuery = lazySchema(() =>
      * Human readable exception list string identifier, e.g. `trusted-linux-processes`. Either `id` or `list_id` must be specified.
      */
     list_id: ExceptionListHumanId.optional(),
+    /**
+      * `single` deletes the list in the current Kibana space; `agnostic` deletes a global list. Must match the
+list you are removing when using `list_id` or `id`.
+
+      */
     namespace_type: ExceptionNamespaceType.optional().default('single'),
   })
 );

@@ -31,6 +31,9 @@ paths:
         - name: namespace_type
           in: query
           required: false
+          description: |
+            `single` deletes the list in the current Kibana space; `agnostic` deletes a global list. Must match the
+            list you are removing when using `list_id` or `id`.
           schema:
             $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType'
             default: single

@@ -33,6 +33,10 @@ export const DeleteExceptionListItemRequestQuery = lazySchema(() =>
      * Human readable exception item string identifier, e.g. `trusted-linux-processes`. Either `id` or `item_id` must be specified
      */
     item_id: ExceptionListItemHumanId.optional(),
+    /**
+      * `single` deletes the item in the current Kibana space; `agnostic` deletes an item in a space-agnostic list. Must match the list that owns the item.
+
+      */
     namespace_type: ExceptionNamespaceType.optional().default('single'),
   })
 );

@@ -26,6 +26,8 @@ paths:
         - name: namespace_type
           in: query
           required: false
+          description: |
+            `single` deletes the item in the current Kibana space; `agnostic` deletes an item in a space-agnostic list. Must match the list that owns the item.
           schema:
             $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType'
             default: single
@@ -76,10 +78,12 @@ paths:
                 oneOf:
                   - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
                   - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
-                example:
-                  statusCode: 400
-                  error: Bad Request
-                  message: "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'"
+              examples:
+                badRequest:
+                  value:
+                    statusCode: 400
+                    error: Bad Request
+                    message: "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'"
         401:
           description: Unsuccessful authentication response
           content:

@@ -24,7 +24,13 @@ import {
 
 export const DuplicateExceptionListRequestQuery = lazySchema(() =>
   z.object({
+    /**
+     * The `list_id` of the existing exception list to copy (source list).
+     */
     list_id: ExceptionListHumanId,
+    /**
+     * Scope in which the source list is defined (`single` = current space, `agnostic` = all spaces).
+     */
     namespace_type: ExceptionNamespaceType,
     /**
      * Determines whether to include expired exceptions in the duplicated list. Expiration date defined by `expire_time`.

@@ -14,11 +14,13 @@ paths:
         - name: list_id
           in: query
           required: true
+          description: The `list_id` of the existing exception list to copy (source list).
           schema:
             $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListHumanId'
         - name: namespace_type
           in: query
           required: true
+          description: Scope in which the source list is defined (`single` = current space, `agnostic` = all spaces).
           schema:
             $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType'
           examples:
@@ -108,14 +110,19 @@ paths:
               examples:
                 notFound:
                   value:
-                    message": 'exception list id: "foo" does not exist'
-                    status_code": 404
+                    message: 'exception list id: "foo" does not exist'
+                    status_code: 404
         405:
           description: Exception list to duplicate not found response
           content:
             application/json:
               schema:
                 $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+              examples:
+                notAllowed:
+                  value:
+                    message: 'Cannot duplicate: list is immutable or the operation is not allowed in this state'
+                    status_code: 405
         500:
           description: Internal server error response
           content:

@@ -24,8 +24,18 @@ import {
 
 export const ExportExceptionListRequestQuery = lazySchema(() =>
   z.object({
+    /**
+     * Exception list's internal `id` (UUID) returned on create; use with `list_id` and `namespace_type` for an unambiguous target.
+     */
     id: ExceptionListId,
+    /**
+     * Human-readable `list_id` of the exception list to export, as shown in the UI and API responses.
+     */
     list_id: ExceptionListHumanId,
+    /**
+      * `single` exports a list in the current Kibana space; `agnostic` exports a global (space-agnostic) list.
+
+      */
     namespace_type: ExceptionNamespaceType,
     /**
      * Determines whether to include expired exceptions in the exported list. Expiration date defined by `expire_time`.

@@ -14,16 +14,20 @@ paths:
         - name: id
           in: query
           required: true
+          description: Exception list's internal `id` (UUID) returned on create; use with `list_id` and `namespace_type` for an unambiguous target.
           schema:
             $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListId'
         - name: list_id
           in: query
           required: true
+          description: Human-readable `list_id` of the exception list to export, as shown in the UI and API responses.
           schema:
             $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListHumanId'
         - name: namespace_type
           in: query
           required: true
+          description: |
+            `single` exports a list in the current Kibana space; `agnostic` exports a global (space-agnostic) list.
           schema:
             $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType'
           examples:

@@ -45,6 +45,10 @@ or available in all spaces (`agnostic` or `single`)
 
       */
     namespace_type: ArrayFromString(ExceptionNamespaceType).optional().default(['single']),
+    /**
+      * Free-text search term applied to exception list item fields (for example a hostname or file path fragment).
+
+      */
     search: z.string().optional(),
     /**
      * The page number to return

@@ -50,6 +50,8 @@ paths:
         - name: search
           in: query
           required: false
+          description: |
+            Free-text search term applied to exception list item fields (for example a hostname or file path fragment).
           schema:
             type: string
             example: host.name

@@ -24,6 +24,10 @@ paths:
                   example: |
                     {"_version":"WzExNDU5LDFd","created_at":"2025-01-09T16:18:17.757Z","created_by":"elastic","description":"This is a sample detection type exception","id":"c86c2da0-2ab6-4343-b81c-216ef27e8d75","immutable":false,"list_id":"simple_list","name":"Sample Detection Exception List","namespace_type":"single","os_types":[],"tags":["user added string for a tag","malware"],"tie_breaker_id":"cf4a7b92-732d-47f0-a0d5-49a35a1736bf","type":"detection","updated_at":"2025-01-09T16:18:17.757Z","updated_by":"elastic","version":1}
                     {"_version":"WzExNDYxLDFd","comments":[],"created_at":"2025-01-09T16:18:42.308Z","created_by":"elastic","description":"This is a sample endpoint type exception","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["some host","another host"],"operator":"included"}],"id":"f37597ce-eaa7-4b64-9100-4301118f6806","item_id":"simple_list_item","list_id":"simple_list","name":"Sample Endpoint Exception List","namespace_type":"single","os_types":["linux"],"tags":["user added string for a tag","malware"],"tie_breaker_id":"4ca3ef3e-9721-42c0-8107-cf47e094d40f","type":"simple","updated_at":"2025-01-09T16:18:42.308Z","updated_by":"elastic"}
+            examples:
+              ndjsonUpload:
+                value:
+                  file: exception_lists.ndjson
       parameters:
         - name: overwrite
           in: query
@@ -115,6 +119,12 @@ paths:
                 oneOf:
                   - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
                   - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+              examples:
+                badRequest:
+                  value:
+                    statusCode: 400
+                    error: Bad Request
+                    message: "Multipart part `file` is required and must contain a valid .ndjson exception list export"
         401:
           description: Unsuccessful authentication response
           content:

@@ -33,6 +33,11 @@ export const ReadExceptionListRequestQuery = lazySchema(() =>
      * Human readable exception list string identifier, e.g. `trusted-linux-processes`. Either `id` or `list_id` must be specified.
      */
     list_id: ExceptionListHumanId.optional(),
+    /**
+      * When `single`, the list is resolved in the current Kibana space. When `agnostic`, the list is a global
+(space-agnostic) container. Required for looking up the correct list when `list_id` is not unique.
+
+      */
     namespace_type: ExceptionNamespaceType.optional().default('single'),
   })
 );

@@ -26,6 +26,9 @@ paths:
         - name: namespace_type
           in: query
           required: false
+          description: |
+            When `single`, the list is resolved in the current Kibana space. When `agnostic`, the list is a global
+            (space-agnostic) container. Required for looking up the correct list when `list_id` is not unique.
           schema:
             $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType'
             default: single

@@ -33,6 +33,11 @@ export const ReadExceptionListItemRequestQuery = lazySchema(() =>
      * Human readable exception item string identifier, e.g. `trusted-linux-processes`. Either `id` or `item_id` must be specified.
      */
     item_id: ExceptionListItemHumanId.optional(),
+    /**
+      * `single` fetches the item in the current space; `agnostic` fetches a global (space-agnostic) item. Must
+match how the list was created.
+
+      */
     namespace_type: ExceptionNamespaceType.optional().default('single'),
   })
 );

@@ -26,6 +26,9 @@ paths:
         - name: namespace_type
           in: query
           required: false
+          description: |
+            `single` fetches the item in the current space; `agnostic` fetches a global (space-agnostic) item. Must
+            match how the list was created.
           schema:
             $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType'
             default: single

@@ -32,6 +32,11 @@ export const ReadExceptionListSummaryRequestQuery = lazySchema(() =>
      * Exception list's human readable identifier.
      */
     list_id: ExceptionListHumanId.optional(),
+    /**
+      * `single` returns summary for a list in the current space; `agnostic` for a space-agnostic list. Must
+line up with `id` / `list_id` used to look up the list.
+
+      */
     namespace_type: ExceptionNamespaceType.optional().default('single'),
     /**
      * Search filter clause

@@ -26,6 +26,9 @@ paths:
         - name: namespace_type
           in: query
           required: false
+          description: |
+            `single` returns summary for a list in the current space; `agnostic` for a space-agnostic list. Must
+            line up with `id` / `list_id` used to look up the list.
           schema:
             $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType'
             default: single

@@ -54,6 +54,15 @@ paths:
                 os_types: [linux]
                 description: Different description
                 name: Updated exception list name
+            examples:
+              fullReplace:
+                value:
+                  list_id: simple_list
+                  tags: [draft, malware]
+                  type: detection
+                  os_types: [linux]
+                  description: Different description
+                  name: Updated exception list name
       responses:
         200:
           description: Successful response

@@ -30,6 +30,14 @@ paths:
                 - $ref: '#/components/schemas/UpdateExceptionListItemBlocklistWindows'
                 - $ref: '#/components/schemas/UpdateExceptionListItemBlocklistLinux'
                 - $ref: '#/components/schemas/UpdateExceptionListItemBlocklistMac'
+            examples:
+              updateItem:
+                value:
+                  id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2
+                  name: Updated name
+                  type: simple
+                  description: Updated description
+                  namespace_type: single
       responses:
         200:
           description: Successful response