[Threat Hunting Investigations] Improve API docs for notes/timeline (#213584)

## Summary

[META
issue](https://github.com/elastic/security-docs-internal/issues/57)

This PR improves the API documentation for timeline/notes/pinned events
as per the definition in the meta issue.

### Notes
#### Timeline API
- `eventType`:
	- is always set to `all`
	- looks like it's been superseded by dataView?
	- I marked it as `deperecated` 
- `eventIdToNoteIds`:
- there's a type mismatch between what the frontend expects and what is
returned
	- also it does not seem to be used anymore?
	- it needs to be investigated further
#### Notes API
- `GlobalNote`:
	- looks like it's not used anymore
	- I removed it, nothing broke
- `eventIngested`, `eventTimestamp`, `eventDataView` and `overrideOwner`
are all not used on the patch note endpoint, I removed them. The
`event*` ones I have never seen before to be honest.

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>

oas_docs/output/kibana.serverless.yaml

@@ -37979,24 +37979,17 @@ paths:
             schema:
               type: object
               properties:
-                eventDataView:
-                  nullable: true
-                  type: string
-                eventIngested:
-                  nullable: true
-                  type: string
-                eventTimestamp:
-                  nullable: true
-                  type: string
                 note:
                   $ref: '#/components/schemas/Security_Timeline_API_BareNote'
+                  description: The note to add or update.
                 noteId:
+                  description: The `savedObjectId` of the note
+                  example: 709f99c6-89b6-4953-9160-35945c8e174e
                   nullable: true
                   type: string
-                overrideOwner:
-                  nullable: true
-                  type: boolean
                 version:
+                  description: The version of the note
+                  example: WzQ2LDFd
                   nullable: true
                   type: string
               required:
@@ -38409,7 +38402,7 @@ paths:
       x-beta: true
   /api/pinned_event:
     patch:
-      description: Pin an event to an existing Timeline.
+      description: Pin/unpin an event to/from an existing Timeline.
       operationId: PersistPinnedEventRoute
       requestBody:
         content:
@@ -38418,16 +38411,22 @@ paths:
               type: object
               properties:
                 eventId:
+                  description: The `_id` of the associated event for this pinned event.
+                  example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
                   type: string
                 pinnedEventId:
+                  description: The `savedObjectId` of the pinned event you want to unpin.
+                  example: 10r1929b-0af7-42bd-85a8-56e234f98h2f3
                   nullable: true
                   type: string
                 timelineId:
+                  description: The `savedObjectId` of the timeline that you want this pinned event unpinned from.
+                  example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
                   type: string
               required:
                 - eventId
                 - timelineId
-        description: The pinned event to add or update, along with additional metadata.
+        description: The pinned event to add or unpin, along with additional metadata.
         required: true
       responses:
         '200':
@@ -38435,8 +38434,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Security_Timeline_API_PersistPinnedEventResponse'
-          description: Indicates the event was successfully pinned to the Timeline.
+          description: Indicates the event was successfully pinned to or unpinned from the Timeline.
-      summary: Pin an event
+      summary: Pin/unpin an event
       tags:
         - Security Timeline API
       x-beta: true
@@ -40382,11 +40381,17 @@ paths:
               type: object
               properties:
                 savedObjectIds:
+                  description: The list of IDs of the Timelines or Timeline templates to delete
+                  example:
+                    - 15c1929b-0af7-42bd-85a8-56e234cc7c4e
                   items:
                     type: string
                   type: array
                 searchIds:
-                  description: Saved search ids that should be deleted alongside the timelines
+                  description: Saved search IDs that should be deleted alongside the timelines
+                  example:
+                    - 23f3-43g34g322-e5g5hrh6h-45454
+                    - 6ce1b592-84e3-4b4a-9552-f189d4b82075
                   items:
                     type: string
                   type: array
@@ -40405,12 +40410,12 @@ paths:
       description: Get the details of an existing saved Timeline or Timeline template.
       operationId: GetTimeline
       parameters:
-        - description: The ID of the template timeline to retrieve
+        - description: The `savedObjectId` of the template timeline to retrieve
           in: query
           name: template_timeline_id
           schema:
             type: string
-        - description: The ID of the Timeline to retrieve.
+        - description: The `savedObjectId` of the Timeline to retrieve.
           in: query
           name: id
           schema:
@@ -40437,10 +40442,15 @@ paths:
               properties:
                 timeline:
                   $ref: '#/components/schemas/Security_Timeline_API_SavedTimeline'
+                  description: The timeline object of the Timeline or Timeline template that you’re updating.
                 timelineId:
+                  description: The `savedObjectId` of the Timeline or Timeline template that you’re updating.
+                  example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
                   nullable: true
                   type: string
                 version:
+                  description: The version of the Timeline or Timeline template that you’re updating.
+                  example: WzE0LDFd
                   nullable: true
                   type: string
               required:
@@ -40455,7 +40465,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Security_Timeline_API_PersistTimelineResponse'
-          description: Indicates that the draft Timeline was successfully created. In the event the user already has a draft Timeline, the existing draft Timeline is cleared and returned.
+          description: Indicates that the Timeline was successfully updated.
         '405':
           content:
             application/json:
@@ -40463,10 +40473,13 @@ paths:
                 type: object
                 properties:
                   body:
+                    description: The error message
+                    example: update timeline error
                     type: string
                   statusCode:
+                    example: 405
                     type: number
-          description: Indicates that the user does not have the required access to create a draft Timeline.
+          description: Indicates that the user does not have the required access to create a Timeline.
       summary: Update a Timeline
       tags:
         - Security Timeline API
@@ -40484,14 +40497,20 @@ paths:
                   $ref: '#/components/schemas/Security_Timeline_API_TimelineStatus'
                   nullable: true
                 templateTimelineId:
+                  description: A unique identifier for the Timeline template.
+                  example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
                   nullable: true
                   type: string
                 templateTimelineVersion:
+                  description: Timeline template version number.
+                  example: 12
                   nullable: true
                   type: number
                 timeline:
                   $ref: '#/components/schemas/Security_Timeline_API_SavedTimeline'
                 timelineId:
+                  description: A unique identifier for the Timeline.
+                  example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
                   nullable: true
                   type: string
                 timelineType:
@@ -40518,8 +40537,11 @@ paths:
                 type: object
                 properties:
                   body:
+                    description: The error message
+                    example: update timeline error
                     type: string
                   statusCode:
+                    example: 405
                     type: number
           description: Indicates that there was an error in the Timeline creation.
       summary: Create a Timeline or Timeline template
@@ -40760,6 +40782,7 @@ paths:
               properties:
                 file: {}
                 isImmutable:
+                  description: Whether the Timeline should be immutable
                   enum:
                     - 'true'
                     - 'false'
@@ -40782,10 +40805,11 @@ paths:
                 type: object
                 properties:
                   body:
-                    type: string
+                    description: The error message
-                  id:
+                    example: Invalid file extension
                     type: string
                   statusCode:
+                    example: 400
                     type: number
           description: Indicates the import of Timelines was unsuccessful because of an invalid file extension.
         '404':
@@ -40794,9 +40818,12 @@ paths:
               schema:
                 type: object
                 properties:
-                  id:
+                  body:
+                    description: The error message
+                    example: Unable to find saved object client
                     type: string
                   statusCode:
+                    example: 404
                     type: number
           description: Indicates that we were unable to locate the saved object client necessary to handle the import.
         '409':
@@ -40806,10 +40833,11 @@ paths:
                 type: object
                 properties:
                   body:
-                    type: string
+                    description: The error message
-                  id:
+                    example: Could not import timelines
                     type: string
                   statusCode:
+                    example: 409
                     type: number
           description: Indicates the import of Timelines was unsuccessful.
       summary: Import Timelines
@@ -40921,24 +40949,28 @@ paths:
           name: sort_field
           schema:
             $ref: '#/components/schemas/Security_Timeline_API_SortFieldTimeline'
-        - in: query
+        - description: Whether to sort the results `ascending` or `descending`
+          in: query
           name: sort_order
           schema:
             enum:
               - asc
               - desc
             type: string
-        - in: query
+        - description: How many results should returned at once
+          in: query
           name: page_size
           schema:
             nullable: true
             type: string
-        - in: query
+        - description: How many pages should be skipped
+          in: query
           name: page_index
           schema:
             nullable: true
             type: string
-        - in: query
+        - description: Allows to search for timelines by their title
+          in: query
           name: search
           schema:
             nullable: true
@@ -40956,20 +40988,32 @@ paths:
                 type: object
                 properties:
                   customTemplateTimelineCount:
+                    description: The amount of custom Timeline templates in the results
+                    example: 2
                     type: number
                   defaultTimelineCount:
+                    description: The amount of `default` type Timelines in the results
+                    example: 90
                     type: number
                   elasticTemplateTimelineCount:
+                    description: The amount of Elastic's Timeline templates in the results
+                    example: 8
                     type: number
                   favoriteCount:
+                    description: The amount of favorited Timelines
+                    example: 5
                     type: number
                   templateTimelineCount:
+                    description: The amount of Timeline templates in the results
+                    example: 10
                     type: number
                   timeline:
                     items:
                       $ref: '#/components/schemas/Security_Timeline_API_TimelineResponse'
                     type: array
                   totalCount:
+                    description: The total amount of results
+                    example: 100
                     type: number
                 required:
                   - timeline
@@ -40982,8 +41026,11 @@ paths:
                 type: object
                 properties:
                   body:
+                    description: The error message
+                    example: get timeline error
                     type: string
                   statusCode:
+                    example: 405
                     type: number
           description: Bad request. The user supplied invalid data.
       summary: Get Timelines or Timeline templates
@@ -55952,52 +55999,42 @@ components:
         - orphan
       type: string
     Security_Timeline_API_BareNote:
-      type: object
+      allOf:
-      properties:
+        - $ref: '#/components/schemas/Security_Timeline_API_NoteCreatedAndUpdatedMetadata'
-        created:
+        - type: object
-          nullable: true
+          properties:
-          type: number
+            eventId:
-        createdBy:
+              description: The `_id` of the associated event for this note.
-          nullable: true
+              example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
-          type: string
+              nullable: true
-        eventId:
+              type: string
-          nullable: true
+            note:
-          type: string
+              description: The text of the note
-        note:
+              example: This is an example text
-          nullable: true
+              nullable: true
-          type: string
+              type: string
-        timelineId:
+            timelineId:
-          type: string
+              description: The `savedObjectId` of the Timeline that this note is associated with
-        updated:
+              example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
-          nullable: true
+              type: string
-          type: number
+          required:
-        updatedBy:
+            - timelineId
-          nullable: true
-          type: string
-      required:
-        - timelineId
     Security_Timeline_API_BarePinnedEvent:
-      type: object
+      allOf:
-      properties:
+        - $ref: '#/components/schemas/Security_Timeline_API_PinnedEventCreatedAndUpdatedMetadata'
-        created:
+        - type: object
-          nullable: true
+          properties:
-          type: number
+            eventId:
-        createdBy:
+              description: The `_id` of the associated event for this pinned event.
-          nullable: true
+              example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
-          type: string
+              type: string
-        eventId:
+            timelineId:
-          type: string
+              description: The `savedObjectId` of the timeline that this pinned event is associated with
-        timelineId:
+              example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
-          type: string
+              type: string
-        updated:
+          required:
-          nullable: true
+            - eventId
-          type: number
+            - timelineId
-        updatedBy:
-          nullable: true
-          type: string
-      required:
-        - eventId
-        - timelineId
     Security_Timeline_API_ColumnHeaderResult:
       type: object
       properties:
@@ -56090,7 +56127,7 @@ components:
           $ref: '#/components/schemas/Security_Timeline_API_DataProviderType'
           nullable: true
     Security_Timeline_API_DataProviderType:
-      description: The type of data provider to create. Valid values are `default` and `template`.
+      description: The type of data provider.
       enum:
         - default
         - template
@@ -56124,6 +56161,10 @@ components:
         - savedObjectId
         - version
     Security_Timeline_API_FavoriteTimelineResult:
+      description: Indicates when and who marked a Timeline as a favorite.
+      example:
+        favoriteDate: 1741337636741
+        userName: elastic
       type: object
       properties:
         favoriteDate:
@@ -56136,6 +56177,16 @@ components:
           nullable: true
           type: string
     Security_Timeline_API_FilterTimelineResult:
+      example:
+        meta:
+          alias: Custom filter name
+          disabled: false
+          index: .alerts-security.alerts-default,logs-*
+          key: '@timestamp'
+          negate: false,
+          type: exists
+          value: exists
+        query: '{"exists":{"field":"@timestamp"}}'
       type: object
       properties:
         exists:
@@ -56209,26 +56260,41 @@ components:
       type: object
       properties:
         errors:
+          description: The list of failed Timeline imports
           items:
             type: object
             properties:
               error:
+                description: The error containing the reason why the timeline could not be imported
                 type: object
                 properties:
                   message:
+                    description: The reason why the timeline could not be imported
+                    example: Malformed JSON
                     type: string
                   status_code:
+                    description: The HTTP status code of the error
+                    example: 400
                     type: number
               id:
+                description: The ID of the timeline that failed to import
+                example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
                 type: string
           type: array
         success:
+          description: Indicates whether any of the Timelines were successfully imports
           type: boolean
         success_count:
+          description: The amount of successfully imported/updated Timelines
+          example: 99
           type: number
         timelines_installed:
+          description: The amount of successfully installed Timelines
+          example: 80
           type: number
         timelines_updated:
+          description: The amount of successfully updated Timelines
+          example: 19
           type: number
     Security_Timeline_API_ImportTimelines:
       allOf:
@@ -56268,18 +56334,46 @@ components:
         - type: object
           properties:
             noteId:
+              description: The `savedObjectId` of the note
+              example: 709f99c6-89b6-4953-9160-35945c8e174e
               type: string
             version:
+              description: The version of the note
+              example: WzQ2LDFd
               type: string
           required:
             - noteId
             - version
+    Security_Timeline_API_NoteCreatedAndUpdatedMetadata:
+      type: object
+      properties:
+        created:
+          description: The time the note was created, using a 13-digit Epoch timestamp.
+          example: 1587468588922
+          nullable: true
+          type: number
+        createdBy:
+          description: The user who created the note.
+          example: casetester
+          nullable: true
+          type: string
+        updated:
+          description: The last time the note was updated, using a 13-digit Epoch timestamp
+          example: 1741344876825
+          nullable: true
+          type: number
+        updatedBy:
+          description: The user who last updated the note
+          example: casetester
+          nullable: true
+          type: string
     Security_Timeline_API_PersistPinnedEventResponse:
       oneOf:
         - $ref: '#/components/schemas/Security_Timeline_API_PinnedEvent'
         - type: object
           properties:
             unpinned:
+              description: Indicates whether the event was successfully unpinned
               type: boolean
           required:
             - unpinned
@@ -56291,12 +56385,39 @@ components:
         - type: object
           properties:
             pinnedEventId:
+              description: The `savedObjectId` of this pinned event
+              example: 10r1929b-0af7-42bd-85a8-56e234f98h2f3
               type: string
             version:
+              description: The version of this pinned event
+              example: WzQ2LDFe
               type: string
           required:
             - pinnedEventId
             - version
+    Security_Timeline_API_PinnedEventCreatedAndUpdatedMetadata:
+      type: object
+      properties:
+        created:
+          description: The time the pinned event was created, using a 13-digit Epoch timestamp.
+          example: 1587468588922
+          nullable: true
+          type: number
+        createdBy:
+          description: The user who created the pinned event.
+          example: casetester
+          nullable: true
+          type: string
+        updated:
+          description: The last time the pinned event was updated, using a 13-digit Epoch timestamp
+          example: 1741344876825
+          nullable: true
+          type: number
+        updatedBy:
+          description: The user who last updated the pinned event
+          example: casetester
+          nullable: true
+          type: string
     Security_Timeline_API_QueryMatchResult:
       type: object
       properties:
@@ -56342,6 +56463,7 @@ components:
       required:
         - note
     Security_Timeline_API_RowRendererId:
+      description: Identifies the available row renderers
       enum:
         - alert
         - alerts
@@ -56383,25 +56505,51 @@ components:
       type: object
       properties:
         columns:
+          description: The Timeline's columns
+          example:
+            - columnHeaderType: not-filtered
+              id: '@timestamp'
+            - columnHeaderType: not-filtered
+              id: event.category
           items:
             $ref: '#/components/schemas/Security_Timeline_API_ColumnHeaderResult'
           nullable: true
           type: array
         created:
+          description: The time the Timeline was created, using a 13-digit Epoch timestamp.
+          example: 1587468588922
           nullable: true
           type: number
         createdBy:
+          description: The user who created the Timeline.
+          example: casetester
           nullable: true
           type: string
         dataProviders:
+          description: Object containing query clauses
+          example:
+            - enabled: true
+              excluded: false
+              id: id-d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b
+              name: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b
+              queryMatch:
+                field: _id,
+                operator: ':'
+                value: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b,
           items:
             $ref: '#/components/schemas/Security_Timeline_API_DataProviderResult'
           nullable: true
           type: array
         dataViewId:
+          description: ID of the Timeline's Data View
+          example: security-solution-default
           nullable: true
           type: string
         dateRange:
+          description: The Timeline's search period.
+          example:
+            end: 1587456479201
+            start: 1587370079200
           nullable: true
           type: object
           properties:
@@ -56418,9 +56566,17 @@ components:
                 - nullable: true
                   type: number
         description:
+          description: The Timeline's description
+          example: Investigating exposure of CVE XYZ
           nullable: true
           type: string
         eqlOptions:
+          description: EQL query that is used in the correlation tab
+          example:
+            eventCategoryField: event.category
+            query: sequence\n[process where process.name == "sudo"]\n[any where true]
+            size: 100
+            timestampField: '@timestamp'
           nullable: true
           type: object
           properties:
@@ -56443,9 +56599,13 @@ components:
               nullable: true
               type: string
         eventType:
+          deprecated: true
+          description: Event types displayed in the Timeline
+          example: all
           nullable: true
           type: string
         excludedRowRendererIds:
+          description: A list of row renderers that should not be used when in `Event renderers` mode
           items:
             $ref: '#/components/schemas/Security_Timeline_API_RowRendererId'
           nullable: true
@@ -56456,53 +56616,72 @@ components:
           nullable: true
           type: array
         filters:
+          description: A list of filters that should be applied to the query
           items:
             $ref: '#/components/schemas/Security_Timeline_API_FilterTimelineResult'
           nullable: true
           type: array
         indexNames:
+          description: A list of index names to use in the query (e.g. when the default data view has been modified)
+          example:
+            - .logs*
           items:
             type: string
           nullable: true
           type: array
         kqlMode:
+          description: |-
+            Indicates whether the KQL bar filters the query results or searches for additional results, where:
+              * `filter`: filters query results
+              * `search`: displays additional search results
+          example: search
           nullable: true
           type: string
         kqlQuery:
           $ref: '#/components/schemas/Security_Timeline_API_SerializedFilterQueryResult'
           nullable: true
         savedQueryId:
+          description: The ID of the saved query that might be used in the Query tab
+          example: c7b16904-02d7-4f32-b8f2-cc20f9625d6e
           nullable: true
           type: string
         savedSearchId:
+          description: The ID of the saved search that is used in the ES|QL tab
+          example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
           nullable: true
           type: string
         sort:
           $ref: '#/components/schemas/Security_Timeline_API_Sort'
           nullable: true
         status:
-          enum:
+          $ref: '#/components/schemas/Security_Timeline_API_TimelineStatus'
-            - active
-            - draft
-            - immutable
           nullable: true
-          type: string
         templateTimelineId:
+          description: A unique ID (UUID) for Timeline templates. For Timelines, the value is `null`.
+          example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
           nullable: true
           type: string
         templateTimelineVersion:
+          description: Timeline template version number. For Timelines, the value is `null`.
+          example: 12
           nullable: true
           type: number
         timelineType:
           $ref: '#/components/schemas/Security_Timeline_API_TimelineType'
           nullable: true
         title:
+          description: The Timeline's title.
+          example: CVE XYZ investigation
           nullable: true
           type: string
         updated:
+          description: The last time the Timeline was updated, using a 13-digit Epoch timestamp
+          example: 1741344876825
           nullable: true
           type: number
         updatedBy:
+          description: The user who last updated the Timeline
+          example: casetester
           nullable: true
           type: string
     Security_Timeline_API_SavedTimelineWithSavedObjectId:
@@ -56511,13 +56690,24 @@ components:
         - type: object
           properties:
             savedObjectId:
+              description: The `savedObjectId` of the Timeline or Timeline template
+              example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
               type: string
             version:
+              description: The version of the Timeline or Timeline template
+              example: WzE0LDFd
               type: string
           required:
             - savedObjectId
             - version
     Security_Timeline_API_SerializedFilterQueryResult:
+      description: KQL bar query.
+      example:
+        filterQuery: null
+        kuery:
+          expression: '_id : *'
+          kind: kuery
+        serializedQuery: '{"bool":{"should":[{"exists":{"field":"_id"}}],"minimum_should_match":1}}'
       type: object
       properties:
         filterQuery:
@@ -56552,6 +56742,10 @@ components:
         - created
       type: string
     Security_Timeline_API_SortObject:
+      description: Object indicating how rows are sorted in the Timeline's grid
+      example:
+        columnId: '@timestamp'
+        sortDirection: desc
       type: object
       properties:
         columnId:
@@ -56570,26 +56764,35 @@ components:
         - type: object
           properties:
             eventIdToNoteIds:
+              description: A list of all the notes that are associated to this Timeline.
               items:
                 $ref: '#/components/schemas/Security_Timeline_API_Note'
               nullable: true
               type: array
             noteIds:
+              description: A list of all the ids of notes that are associated to this Timeline.
+              example:
+                - 709f99c6-89b6-4953-9160-35945c8e174e
               items:
                 type: string
               nullable: true
               type: array
             notes:
+              description: A list of all the notes that are associated to this Timeline.
               items:
                 $ref: '#/components/schemas/Security_Timeline_API_Note'
               nullable: true
               type: array
             pinnedEventIds:
+              description: A list of all the ids of pinned events that are associated to this Timeline.
+              example:
+                - 983f99c6-89b6-4953-9160-35945c8a194f
               items:
                 type: string
               nullable: true
               type: array
             pinnedEventsSaveObject:
+              description: A list of all the pinned events that are associated to this Timeline.
               items:
                 $ref: '#/components/schemas/Security_Timeline_API_PinnedEvent'
               nullable: true
@@ -56632,14 +56835,14 @@ components:
             - savedObjectId
             - version
     Security_Timeline_API_TimelineStatus:
-      description: The status of the timeline. Valid values are `active`, `draft`, and `immutable`.
+      description: The status of the Timeline.
       enum:
         - active
         - draft
         - immutable
       type: string
     Security_Timeline_API_TimelineType:
-      description: The type of timeline to create. Valid values are `default` and `template`.
+      description: The type of Timeline.
       enum:
         - default
         - template

oas_docs/output/kibana.yaml

@@ -40087,24 +40087,17 @@ paths:
             schema:
               type: object
               properties:
-                eventDataView:
-                  nullable: true
-                  type: string
-                eventIngested:
-                  nullable: true
-                  type: string
-                eventTimestamp:
-                  nullable: true
-                  type: string
                 note:
                   $ref: '#/components/schemas/Security_Timeline_API_BareNote'
+                  description: The note to add or update.
                 noteId:
+                  description: The `savedObjectId` of the note
+                  example: 709f99c6-89b6-4953-9160-35945c8e174e
                   nullable: true
                   type: string
-                overrideOwner:
-                  nullable: true
-                  type: boolean
                 version:
+                  description: The version of the note
+                  example: WzQ2LDFd
                   nullable: true
                   type: string
               required:
@@ -40502,7 +40495,7 @@ paths:
         - Security Osquery API
   /api/pinned_event:
     patch:
-      description: Pin an event to an existing Timeline.
+      description: Pin/unpin an event to/from an existing Timeline.
       operationId: PersistPinnedEventRoute
       requestBody:
         content:
@@ -40511,16 +40504,22 @@ paths:
               type: object
               properties:
                 eventId:
+                  description: The `_id` of the associated event for this pinned event.
+                  example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
                   type: string
                 pinnedEventId:
+                  description: The `savedObjectId` of the pinned event you want to unpin.
+                  example: 10r1929b-0af7-42bd-85a8-56e234f98h2f3
                   nullable: true
                   type: string
                 timelineId:
+                  description: The `savedObjectId` of the timeline that you want this pinned event unpinned from.
+                  example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
                   type: string
               required:
                 - eventId
                 - timelineId
-        description: The pinned event to add or update, along with additional metadata.
+        description: The pinned event to add or unpin, along with additional metadata.
         required: true
       responses:
         '200':
@@ -40528,8 +40527,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Security_Timeline_API_PersistPinnedEventResponse'
-          description: Indicates the event was successfully pinned to the Timeline.
+          description: Indicates the event was successfully pinned to or unpinned from the Timeline.
-      summary: Pin an event
+      summary: Pin/unpin an event
       tags:
         - Security Timeline API
   /api/risk_score/engine/dangerously_delete_data:
@@ -43458,11 +43457,17 @@ paths:
               type: object
               properties:
                 savedObjectIds:
+                  description: The list of IDs of the Timelines or Timeline templates to delete
+                  example:
+                    - 15c1929b-0af7-42bd-85a8-56e234cc7c4e
                   items:
                     type: string
                   type: array
                 searchIds:
-                  description: Saved search ids that should be deleted alongside the timelines
+                  description: Saved search IDs that should be deleted alongside the timelines
+                  example:
+                    - 23f3-43g34g322-e5g5hrh6h-45454
+                    - 6ce1b592-84e3-4b4a-9552-f189d4b82075
                   items:
                     type: string
                   type: array
@@ -43480,12 +43485,12 @@ paths:
       description: Get the details of an existing saved Timeline or Timeline template.
       operationId: GetTimeline
       parameters:
-        - description: The ID of the template timeline to retrieve
+        - description: The `savedObjectId` of the template timeline to retrieve
           in: query
           name: template_timeline_id
           schema:
             type: string
-        - description: The ID of the Timeline to retrieve.
+        - description: The `savedObjectId` of the Timeline to retrieve.
           in: query
           name: id
           schema:
@@ -43511,10 +43516,15 @@ paths:
               properties:
                 timeline:
                   $ref: '#/components/schemas/Security_Timeline_API_SavedTimeline'
+                  description: The timeline object of the Timeline or Timeline template that you’re updating.
                 timelineId:
+                  description: The `savedObjectId` of the Timeline or Timeline template that you’re updating.
+                  example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
                   nullable: true
                   type: string
                 version:
+                  description: The version of the Timeline or Timeline template that you’re updating.
+                  example: WzE0LDFd
                   nullable: true
                   type: string
               required:
@@ -43529,7 +43539,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Security_Timeline_API_PersistTimelineResponse'
-          description: Indicates that the draft Timeline was successfully created. In the event the user already has a draft Timeline, the existing draft Timeline is cleared and returned.
+          description: Indicates that the Timeline was successfully updated.
         '405':
           content:
             application/json:
@@ -43537,10 +43547,13 @@ paths:
                 type: object
                 properties:
                   body:
+                    description: The error message
+                    example: update timeline error
                     type: string
                   statusCode:
+                    example: 405
                     type: number
-          description: Indicates that the user does not have the required access to create a draft Timeline.
+          description: Indicates that the user does not have the required access to create a Timeline.
       summary: Update a Timeline
       tags:
         - Security Timeline API
@@ -43557,14 +43570,20 @@ paths:
                   $ref: '#/components/schemas/Security_Timeline_API_TimelineStatus'
                   nullable: true
                 templateTimelineId:
+                  description: A unique identifier for the Timeline template.
+                  example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
                   nullable: true
                   type: string
                 templateTimelineVersion:
+                  description: Timeline template version number.
+                  example: 12
                   nullable: true
                   type: number
                 timeline:
                   $ref: '#/components/schemas/Security_Timeline_API_SavedTimeline'
                 timelineId:
+                  description: A unique identifier for the Timeline.
+                  example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
                   nullable: true
                   type: string
                 timelineType:
@@ -43591,8 +43610,11 @@ paths:
                 type: object
                 properties:
                   body:
+                    description: The error message
+                    example: update timeline error
                     type: string
                   statusCode:
+                    example: 405
                     type: number
           description: Indicates that there was an error in the Timeline creation.
       summary: Create a Timeline or Timeline template
@@ -43827,6 +43849,7 @@ paths:
               properties:
                 file: {}
                 isImmutable:
+                  description: Whether the Timeline should be immutable
                   enum:
                     - 'true'
                     - 'false'
@@ -43849,10 +43872,11 @@ paths:
                 type: object
                 properties:
                   body:
-                    type: string
+                    description: The error message
-                  id:
+                    example: Invalid file extension
                     type: string
                   statusCode:
+                    example: 400
                     type: number
           description: Indicates the import of Timelines was unsuccessful because of an invalid file extension.
         '404':
@@ -43861,9 +43885,12 @@ paths:
               schema:
                 type: object
                 properties:
-                  id:
+                  body:
+                    description: The error message
+                    example: Unable to find saved object client
                     type: string
                   statusCode:
+                    example: 404
                     type: number
           description: Indicates that we were unable to locate the saved object client necessary to handle the import.
         '409':
@@ -43873,10 +43900,11 @@ paths:
                 type: object
                 properties:
                   body:
-                    type: string
+                    description: The error message
-                  id:
+                    example: Could not import timelines
                     type: string
                   statusCode:
+                    example: 409
                     type: number
           description: Indicates the import of Timelines was unsuccessful.
       summary: Import Timelines
@@ -43985,24 +44013,28 @@ paths:
           name: sort_field
           schema:
             $ref: '#/components/schemas/Security_Timeline_API_SortFieldTimeline'
-        - in: query
+        - description: Whether to sort the results `ascending` or `descending`
+          in: query
           name: sort_order
           schema:
             enum:
               - asc
               - desc
             type: string
-        - in: query
+        - description: How many results should returned at once
+          in: query
           name: page_size
           schema:
             nullable: true
             type: string
-        - in: query
+        - description: How many pages should be skipped
+          in: query
           name: page_index
           schema:
             nullable: true
             type: string
-        - in: query
+        - description: Allows to search for timelines by their title
+          in: query
           name: search
           schema:
             nullable: true
@@ -44020,20 +44052,32 @@ paths:
                 type: object
                 properties:
                   customTemplateTimelineCount:
+                    description: The amount of custom Timeline templates in the results
+                    example: 2
                     type: number
                   defaultTimelineCount:
+                    description: The amount of `default` type Timelines in the results
+                    example: 90
                     type: number
                   elasticTemplateTimelineCount:
+                    description: The amount of Elastic's Timeline templates in the results
+                    example: 8
                     type: number
                   favoriteCount:
+                    description: The amount of favorited Timelines
+                    example: 5
                     type: number
                   templateTimelineCount:
+                    description: The amount of Timeline templates in the results
+                    example: 10
                     type: number
                   timeline:
                     items:
                       $ref: '#/components/schemas/Security_Timeline_API_TimelineResponse'
                     type: array
                   totalCount:
+                    description: The total amount of results
+                    example: 100
                     type: number
                 required:
                   - timeline
@@ -44046,8 +44090,11 @@ paths:
                 type: object
                 properties:
                   body:
+                    description: The error message
+                    example: get timeline error
                     type: string
                   statusCode:
+                    example: 405
                     type: number
           description: Bad request. The user supplied invalid data.
       summary: Get Timelines or Timeline templates
@@ -63313,52 +63360,42 @@ components:
         - orphan
       type: string
     Security_Timeline_API_BareNote:
-      type: object
+      allOf:
-      properties:
+        - $ref: '#/components/schemas/Security_Timeline_API_NoteCreatedAndUpdatedMetadata'
-        created:
+        - type: object
-          nullable: true
+          properties:
-          type: number
+            eventId:
-        createdBy:
+              description: The `_id` of the associated event for this note.
-          nullable: true
+              example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
-          type: string
+              nullable: true
-        eventId:
+              type: string
-          nullable: true
+            note:
-          type: string
+              description: The text of the note
-        note:
+              example: This is an example text
-          nullable: true
+              nullable: true
-          type: string
+              type: string
-        timelineId:
+            timelineId:
-          type: string
+              description: The `savedObjectId` of the Timeline that this note is associated with
-        updated:
+              example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
-          nullable: true
+              type: string
-          type: number
+          required:
-        updatedBy:
+            - timelineId
-          nullable: true
-          type: string
-      required:
-        - timelineId
     Security_Timeline_API_BarePinnedEvent:
-      type: object
+      allOf:
-      properties:
+        - $ref: '#/components/schemas/Security_Timeline_API_PinnedEventCreatedAndUpdatedMetadata'
-        created:
+        - type: object
-          nullable: true
+          properties:
-          type: number
+            eventId:
-        createdBy:
+              description: The `_id` of the associated event for this pinned event.
-          nullable: true
+              example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
-          type: string
+              type: string
-        eventId:
+            timelineId:
-          type: string
+              description: The `savedObjectId` of the timeline that this pinned event is associated with
-        timelineId:
+              example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
-          type: string
+              type: string
-        updated:
+          required:
-          nullable: true
+            - eventId
-          type: number
+            - timelineId
-        updatedBy:
-          nullable: true
-          type: string
-      required:
-        - eventId
-        - timelineId
     Security_Timeline_API_ColumnHeaderResult:
       type: object
       properties:
@@ -63451,7 +63488,7 @@ components:
           $ref: '#/components/schemas/Security_Timeline_API_DataProviderType'
           nullable: true
     Security_Timeline_API_DataProviderType:
-      description: The type of data provider to create. Valid values are `default` and `template`.
+      description: The type of data provider.
       enum:
         - default
         - template
@@ -63485,6 +63522,10 @@ components:
         - savedObjectId
         - version
     Security_Timeline_API_FavoriteTimelineResult:
+      description: Indicates when and who marked a Timeline as a favorite.
+      example:
+        favoriteDate: 1741337636741
+        userName: elastic
       type: object
       properties:
         favoriteDate:
@@ -63497,6 +63538,16 @@ components:
           nullable: true
           type: string
     Security_Timeline_API_FilterTimelineResult:
+      example:
+        meta:
+          alias: Custom filter name
+          disabled: false
+          index: .alerts-security.alerts-default,logs-*
+          key: '@timestamp'
+          negate: false,
+          type: exists
+          value: exists
+        query: '{"exists":{"field":"@timestamp"}}'
       type: object
       properties:
         exists:
@@ -63570,26 +63621,41 @@ components:
       type: object
       properties:
         errors:
+          description: The list of failed Timeline imports
           items:
             type: object
             properties:
               error:
+                description: The error containing the reason why the timeline could not be imported
                 type: object
                 properties:
                   message:
+                    description: The reason why the timeline could not be imported
+                    example: Malformed JSON
                     type: string
                   status_code:
+                    description: The HTTP status code of the error
+                    example: 400
                     type: number
               id:
+                description: The ID of the timeline that failed to import
+                example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
                 type: string
           type: array
         success:
+          description: Indicates whether any of the Timelines were successfully imports
           type: boolean
         success_count:
+          description: The amount of successfully imported/updated Timelines
+          example: 99
           type: number
         timelines_installed:
+          description: The amount of successfully installed Timelines
+          example: 80
           type: number
         timelines_updated:
+          description: The amount of successfully updated Timelines
+          example: 19
           type: number
     Security_Timeline_API_ImportTimelines:
       allOf:
@@ -63629,18 +63695,46 @@ components:
         - type: object
           properties:
             noteId:
+              description: The `savedObjectId` of the note
+              example: 709f99c6-89b6-4953-9160-35945c8e174e
               type: string
             version:
+              description: The version of the note
+              example: WzQ2LDFd
               type: string
           required:
             - noteId
             - version
+    Security_Timeline_API_NoteCreatedAndUpdatedMetadata:
+      type: object
+      properties:
+        created:
+          description: The time the note was created, using a 13-digit Epoch timestamp.
+          example: 1587468588922
+          nullable: true
+          type: number
+        createdBy:
+          description: The user who created the note.
+          example: casetester
+          nullable: true
+          type: string
+        updated:
+          description: The last time the note was updated, using a 13-digit Epoch timestamp
+          example: 1741344876825
+          nullable: true
+          type: number
+        updatedBy:
+          description: The user who last updated the note
+          example: casetester
+          nullable: true
+          type: string
     Security_Timeline_API_PersistPinnedEventResponse:
       oneOf:
         - $ref: '#/components/schemas/Security_Timeline_API_PinnedEvent'
         - type: object
           properties:
             unpinned:
+              description: Indicates whether the event was successfully unpinned
               type: boolean
           required:
             - unpinned
@@ -63652,12 +63746,39 @@ components:
         - type: object
           properties:
             pinnedEventId:
+              description: The `savedObjectId` of this pinned event
+              example: 10r1929b-0af7-42bd-85a8-56e234f98h2f3
               type: string
             version:
+              description: The version of this pinned event
+              example: WzQ2LDFe
               type: string
           required:
             - pinnedEventId
             - version
+    Security_Timeline_API_PinnedEventCreatedAndUpdatedMetadata:
+      type: object
+      properties:
+        created:
+          description: The time the pinned event was created, using a 13-digit Epoch timestamp.
+          example: 1587468588922
+          nullable: true
+          type: number
+        createdBy:
+          description: The user who created the pinned event.
+          example: casetester
+          nullable: true
+          type: string
+        updated:
+          description: The last time the pinned event was updated, using a 13-digit Epoch timestamp
+          example: 1741344876825
+          nullable: true
+          type: number
+        updatedBy:
+          description: The user who last updated the pinned event
+          example: casetester
+          nullable: true
+          type: string
     Security_Timeline_API_QueryMatchResult:
       type: object
       properties:
@@ -63703,6 +63824,7 @@ components:
       required:
         - note
     Security_Timeline_API_RowRendererId:
+      description: Identifies the available row renderers
       enum:
         - alert
         - alerts
@@ -63744,25 +63866,51 @@ components:
       type: object
       properties:
         columns:
+          description: The Timeline's columns
+          example:
+            - columnHeaderType: not-filtered
+              id: '@timestamp'
+            - columnHeaderType: not-filtered
+              id: event.category
           items:
             $ref: '#/components/schemas/Security_Timeline_API_ColumnHeaderResult'
           nullable: true
           type: array
         created:
+          description: The time the Timeline was created, using a 13-digit Epoch timestamp.
+          example: 1587468588922
           nullable: true
           type: number
         createdBy:
+          description: The user who created the Timeline.
+          example: casetester
           nullable: true
           type: string
         dataProviders:
+          description: Object containing query clauses
+          example:
+            - enabled: true
+              excluded: false
+              id: id-d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b
+              name: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b
+              queryMatch:
+                field: _id,
+                operator: ':'
+                value: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b,
           items:
             $ref: '#/components/schemas/Security_Timeline_API_DataProviderResult'
           nullable: true
           type: array
         dataViewId:
+          description: ID of the Timeline's Data View
+          example: security-solution-default
           nullable: true
           type: string
         dateRange:
+          description: The Timeline's search period.
+          example:
+            end: 1587456479201
+            start: 1587370079200
           nullable: true
           type: object
           properties:
@@ -63779,9 +63927,17 @@ components:
                 - nullable: true
                   type: number
         description:
+          description: The Timeline's description
+          example: Investigating exposure of CVE XYZ
           nullable: true
           type: string
         eqlOptions:
+          description: EQL query that is used in the correlation tab
+          example:
+            eventCategoryField: event.category
+            query: sequence\n[process where process.name == "sudo"]\n[any where true]
+            size: 100
+            timestampField: '@timestamp'
           nullable: true
           type: object
           properties:
@@ -63804,9 +63960,13 @@ components:
               nullable: true
               type: string
         eventType:
+          deprecated: true
+          description: Event types displayed in the Timeline
+          example: all
           nullable: true
           type: string
         excludedRowRendererIds:
+          description: A list of row renderers that should not be used when in `Event renderers` mode
           items:
             $ref: '#/components/schemas/Security_Timeline_API_RowRendererId'
           nullable: true
@@ -63817,53 +63977,72 @@ components:
           nullable: true
           type: array
         filters:
+          description: A list of filters that should be applied to the query
           items:
             $ref: '#/components/schemas/Security_Timeline_API_FilterTimelineResult'
           nullable: true
           type: array
         indexNames:
+          description: A list of index names to use in the query (e.g. when the default data view has been modified)
+          example:
+            - .logs*
           items:
             type: string
           nullable: true
           type: array
         kqlMode:
+          description: |-
+            Indicates whether the KQL bar filters the query results or searches for additional results, where:
+              * `filter`: filters query results
+              * `search`: displays additional search results
+          example: search
           nullable: true
           type: string
         kqlQuery:
           $ref: '#/components/schemas/Security_Timeline_API_SerializedFilterQueryResult'
           nullable: true
         savedQueryId:
+          description: The ID of the saved query that might be used in the Query tab
+          example: c7b16904-02d7-4f32-b8f2-cc20f9625d6e
           nullable: true
           type: string
         savedSearchId:
+          description: The ID of the saved search that is used in the ES|QL tab
+          example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
           nullable: true
           type: string
         sort:
           $ref: '#/components/schemas/Security_Timeline_API_Sort'
           nullable: true
         status:
-          enum:
+          $ref: '#/components/schemas/Security_Timeline_API_TimelineStatus'
-            - active
-            - draft
-            - immutable
           nullable: true
-          type: string
         templateTimelineId:
+          description: A unique ID (UUID) for Timeline templates. For Timelines, the value is `null`.
+          example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
           nullable: true
           type: string
         templateTimelineVersion:
+          description: Timeline template version number. For Timelines, the value is `null`.
+          example: 12
           nullable: true
           type: number
         timelineType:
           $ref: '#/components/schemas/Security_Timeline_API_TimelineType'
           nullable: true
         title:
+          description: The Timeline's title.
+          example: CVE XYZ investigation
           nullable: true
           type: string
         updated:
+          description: The last time the Timeline was updated, using a 13-digit Epoch timestamp
+          example: 1741344876825
           nullable: true
           type: number
         updatedBy:
+          description: The user who last updated the Timeline
+          example: casetester
           nullable: true
           type: string
     Security_Timeline_API_SavedTimelineWithSavedObjectId:
@@ -63872,13 +64051,24 @@ components:
         - type: object
           properties:
             savedObjectId:
+              description: The `savedObjectId` of the Timeline or Timeline template
+              example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
               type: string
             version:
+              description: The version of the Timeline or Timeline template
+              example: WzE0LDFd
               type: string
           required:
             - savedObjectId
             - version
     Security_Timeline_API_SerializedFilterQueryResult:
+      description: KQL bar query.
+      example:
+        filterQuery: null
+        kuery:
+          expression: '_id : *'
+          kind: kuery
+        serializedQuery: '{"bool":{"should":[{"exists":{"field":"_id"}}],"minimum_should_match":1}}'
       type: object
       properties:
         filterQuery:
@@ -63913,6 +64103,10 @@ components:
         - created
       type: string
     Security_Timeline_API_SortObject:
+      description: Object indicating how rows are sorted in the Timeline's grid
+      example:
+        columnId: '@timestamp'
+        sortDirection: desc
       type: object
       properties:
         columnId:
@@ -63931,26 +64125,35 @@ components:
         - type: object
           properties:
             eventIdToNoteIds:
+              description: A list of all the notes that are associated to this Timeline.
               items:
                 $ref: '#/components/schemas/Security_Timeline_API_Note'
               nullable: true
               type: array
             noteIds:
+              description: A list of all the ids of notes that are associated to this Timeline.
+              example:
+                - 709f99c6-89b6-4953-9160-35945c8e174e
               items:
                 type: string
               nullable: true
               type: array
             notes:
+              description: A list of all the notes that are associated to this Timeline.
               items:
                 $ref: '#/components/schemas/Security_Timeline_API_Note'
               nullable: true
               type: array
             pinnedEventIds:
+              description: A list of all the ids of pinned events that are associated to this Timeline.
+              example:
+                - 983f99c6-89b6-4953-9160-35945c8a194f
               items:
                 type: string
               nullable: true
               type: array
             pinnedEventsSaveObject:
+              description: A list of all the pinned events that are associated to this Timeline.
               items:
                 $ref: '#/components/schemas/Security_Timeline_API_PinnedEvent'
               nullable: true
@@ -63993,14 +64196,14 @@ components:
             - savedObjectId
             - version
     Security_Timeline_API_TimelineStatus:
-      description: The status of the timeline. Valid values are `active`, `draft`, and `immutable`.
+      description: The status of the Timeline.
       enum:
         - active
         - draft
         - immutable
       type: string
     Security_Timeline_API_TimelineType:
-      description: The type of timeline to create. Valid values are `default` and `template`.
+      description: The type of Timeline.
       enum:
         - default
         - template

x-pack/solutions/security/plugins/security_solution/common/api/quickstart_client.gen.ts

@@ -1872,7 +1872,7 @@ finalize it.
       .catch(catchAxiosErrorFormatAndThrow);
   }
   /**
-   * Pin an event to an existing Timeline.
+   * Pin/unpin an event to/from an existing Timeline.
    */
   async persistPinnedEventRoute(props: PersistPinnedEventRouteProps) {
     this.log.info(`${new Date().toISOString()} Calling API PersistPinnedEventRoute`);

x-pack/solutions/security/plugins/security_solution/common/api/timeline/create_timelines/create_timelines_route.gen.ts

@@ -27,9 +27,18 @@ export type CreateTimelinesRequestBody = z.infer<typeof CreateTimelinesRequestBo
 export const CreateTimelinesRequestBody = z.object({
   timeline: SavedTimeline,
   status: TimelineStatus.nullable().optional(),
-  timelineId: z.string().nullable().optional(),
+  /**
+   * A unique identifier for the Timeline template.
+   */
   templateTimelineId: z.string().nullable().optional(),
+  /**
+   * Timeline template version number.
+   */
   templateTimelineVersion: z.number().nullable().optional(),
+  /**
+   * A unique identifier for the Timeline.
+   */
+  timelineId: z.string().nullable().optional(),
   timelineType: TimelineType.nullable().optional(),
   version: z.string().nullable().optional(),
 });

x-pack/solutions/security/plugins/security_solution/common/api/timeline/create_timelines/create_timelines_route.schema.yaml

@@ -29,15 +29,21 @@ paths:
                 status:
                   $ref: '../model/components.schema.yaml#/components/schemas/TimelineStatus'
                   nullable: true
-                timelineId:
-                  type: string
-                  nullable: true
                 templateTimelineId:
                   type: string
                   nullable: true
+                  description: A unique identifier for the Timeline template.
+                  example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
                 templateTimelineVersion:
                   type: number
                   nullable: true
+                  description: Timeline template version number.
+                  example: 12
+                timelineId:
+                  type: string
+                  nullable: true
+                  description: A unique identifier for the Timeline.
+                  example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
                 timelineType:
                   $ref: '../model/components.schema.yaml#/components/schemas/TimelineType'
                   nullable: true
@@ -60,5 +66,8 @@ paths:
                 properties:
                   body:
                     type: string
+                    description: The error message
+                    example: update timeline error
                   statusCode:
                     type: number
+                    example: 405

x-pack/solutions/security/plugins/security_solution/common/api/timeline/delete_timelines/delete_timelines_route.gen.ts

@@ -18,9 +18,12 @@ import { z } from '@kbn/zod';
 
 export type DeleteTimelinesRequestBody = z.infer<typeof DeleteTimelinesRequestBody>;
 export const DeleteTimelinesRequestBody = z.object({
+  /**
+   * The list of IDs of the Timelines or Timeline templates to delete
+   */
   savedObjectIds: z.array(z.string()),
   /**
-   * Saved search ids that should be deleted alongside the timelines
+   * Saved search IDs that should be deleted alongside the timelines
    */
   searchIds: z.array(z.string()).optional(),
 });

x-pack/solutions/security/plugins/security_solution/common/api/timeline/delete_timelines/delete_timelines_route.schema.yaml

@@ -28,11 +28,17 @@ paths:
                   type: array
                   items:
                     type: string
+                  description: The list of IDs of the Timelines or Timeline templates to delete
+                  example:
+                    - '15c1929b-0af7-42bd-85a8-56e234cc7c4e'
                 searchIds:
                   type: array
-                  description: Saved search ids that should be deleted alongside the timelines
+                  description: Saved search IDs that should be deleted alongside the timelines
                   items:
                     type: string
+                  example:
+                    - 23f3-43g34g322-e5g5hrh6h-45454
+                    - 6ce1b592-84e3-4b4a-9552-f189d4b82075
       responses:
         '200':
           description: Indicates the Timeline was successfully deleted.

x-pack/solutions/security/plugins/security_solution/common/api/timeline/get_timeline/get_timeline_route.gen.ts

@@ -21,11 +21,11 @@ import { TimelineResponse } from '../model/components.gen';
 export type GetTimelineRequestQuery = z.infer<typeof GetTimelineRequestQuery>;
 export const GetTimelineRequestQuery = z.object({
   /**
-   * The ID of the template timeline to retrieve
+   * The `savedObjectId` of the template timeline to retrieve
    */
   template_timeline_id: z.string().optional(),
   /**
-   * The ID of the Timeline to retrieve.
+   * The `savedObjectId` of the Timeline to retrieve.
    */
   id: z.string().optional(),
 });

x-pack/solutions/security/plugins/security_solution/common/api/timeline/get_timeline/get_timeline_route.schema.yaml

@@ -20,12 +20,12 @@ paths:
           name: template_timeline_id
           schema:
             type: string
-          description: The ID of the template timeline to retrieve
+          description: The `savedObjectId` of the template timeline to retrieve
         - in: query
           name: id
           schema:
             type: string
-          description: The ID of the Timeline to retrieve.
+          description: The `savedObjectId` of the Timeline to retrieve.
       responses:
         '200':
           description: Indicates that the (template) Timeline was found and returned.

x-pack/solutions/security/plugins/security_solution/common/api/timeline/get_timelines/get_timelines_route.gen.ts

@@ -31,9 +31,21 @@ export const GetTimelinesRequestQuery = z.object({
   only_user_favorite: z.enum(['true', 'false']).nullable().optional(),
   timeline_type: TimelineType.nullable().optional(),
   sort_field: SortFieldTimeline.optional(),
+  /**
+   * Whether to sort the results `ascending` or `descending`
+   */
   sort_order: z.enum(['asc', 'desc']).optional(),
+  /**
+   * How many results should returned at once
+   */
   page_size: z.string().nullable().optional(),
+  /**
+   * How many pages should be skipped
+   */
   page_index: z.string().nullable().optional(),
+  /**
+   * Allows to search for timelines by their title
+   */
   search: z.string().nullable().optional(),
   status: TimelineStatus.nullable().optional(),
 });
@@ -42,10 +54,28 @@ export type GetTimelinesRequestQueryInput = z.input<typeof GetTimelinesRequestQu
 export type GetTimelinesResponse = z.infer<typeof GetTimelinesResponse>;
 export const GetTimelinesResponse = z.object({
   timeline: z.array(TimelineResponse),
+  /**
+   * The total amount of results
+   */
   totalCount: z.number(),
+  /**
+   * The amount of `default` type Timelines in the results
+   */
   defaultTimelineCount: z.number().optional(),
+  /**
+   * The amount of Timeline templates in the results
+   */
   templateTimelineCount: z.number().optional(),
+  /**
+   * The amount of favorited Timelines
+   */
   favoriteCount: z.number().optional(),
+  /**
+   * The amount of Elastic's Timeline templates in the results
+   */
   elasticTemplateTimelineCount: z.number().optional(),
+  /**
+   * The amount of custom Timeline templates in the results
+   */
   customTemplateTimelineCount: z.number().optional(),
 });

x-pack/solutions/security/plugins/security_solution/common/api/timeline/get_timelines/get_timelines_route.schema.yaml

@@ -36,6 +36,7 @@ paths:
             $ref: '../model/components.schema.yaml#/components/schemas/SortFieldTimeline'
         - in: query
           name: sort_order
+          description: Whether to sort the results `ascending` or `descending`
           schema:
             type: string
             enum:
@@ -43,16 +44,19 @@ paths:
               - desc
         - in: query
           name: page_size
+          description: How many results should returned at once
           schema:
             nullable: true
             type: string
         - in: query
           name: page_index
+          description: How many pages should be skipped
           schema:
             nullable: true
             type: string
         - in: query
           name: search
+          description: Allows to search for timelines by their title
           schema:
             nullable: true
             type: string
@@ -68,10 +72,7 @@ paths:
             application/json:
               schema:
                 type: object
-                required: [
+                required: [timeline, totalCount]
-                  timeline,
-                  totalCount,
-                ]
                 properties:
                   timeline:
                     type: array
@@ -79,16 +80,28 @@ paths:
                       $ref: '../model/components.schema.yaml#/components/schemas/TimelineResponse'
                   totalCount:
                     type: number
+                    description: The total amount of results
+                    example: 100
                   defaultTimelineCount:
                     type: number
+                    description: The amount of `default` type Timelines in the results
+                    example: 90
                   templateTimelineCount:
                     type: number
+                    description: The amount of Timeline templates in the results
+                    example: 10
                   favoriteCount:
                     type: number
+                    description: The amount of favorited Timelines
+                    example: 5
                   elasticTemplateTimelineCount:
                     type: number
+                    description: The amount of Elastic's Timeline templates in the results
+                    example: 8
                   customTemplateTimelineCount:
                     type: number
+                    description: The amount of custom Timeline templates in the results
+                    example: 2
         '400':
           description: Bad request. The user supplied invalid data.
           content:
@@ -98,5 +111,8 @@ paths:
                 properties:
                   body:
                     type: string
+                    description: The error message
+                    example: get timeline error
                   statusCode:
                     type: number
+                    example: 405

x-pack/solutions/security/plugins/security_solution/common/api/timeline/import_timelines/import_timelines_route.gen.ts

@@ -20,6 +20,9 @@ import { ImportTimelineResult } from '../model/components.gen';
 
 export type ImportTimelinesRequestBody = z.infer<typeof ImportTimelinesRequestBody>;
 export const ImportTimelinesRequestBody = z.object({
+  /**
+   * Whether the Timeline should be immutable
+   */
   isImmutable: z.enum(['true', 'false']).optional(),
   file: z.unknown(),
 });

x-pack/solutions/security/plugins/security_solution/common/api/timeline/import_timelines/import_timelines_route.schema.yaml

@@ -29,6 +29,7 @@ paths:
                   enum:
                     - 'true'
                     - 'false'
+                  description: Whether the Timeline should be immutable
                 file: {}
       responses:
         '200':
@@ -45,12 +46,13 @@ paths:
               schema:
                 type: object
                 properties:
-                  id:
-                    type: string
                   body:
                     type: string
+                    description: The error message
+                    example: Invalid file extension
                   statusCode:
                     type: number
+                    example: 400
 
         '404':
           description: Indicates that we were unable to locate the saved object client necessary to handle the import.
@@ -59,10 +61,13 @@ paths:
               schema:
                 type: object
                 properties:
-                  id:
+                  body:
                     type: string
+                    description: The error message
+                    example: Unable to find saved object client
                   statusCode:
                     type: number
+                    example: 404
         '409':
           description: Indicates the import of Timelines was unsuccessful.
           content:
@@ -70,9 +75,10 @@ paths:
               schema:
                 type: object
                 properties:
-                  id:
-                    type: string
                   body:
                     type: string
+                    description: The error message
+                    example: Could not import timelines
                   statusCode:
                     type: number
+                    example: 409

x-pack/solutions/security/plugins/security_solution/common/api/timeline/model/components.gen.ts

@@ -17,7 +17,7 @@
 import { z } from '@kbn/zod';
 
 /**
- * The type of timeline to create. Valid values are `default` and `template`.
+ * The type of Timeline.
  */
 export type TimelineType = z.infer<typeof TimelineType>;
 export const TimelineType = z.enum(['default', 'template']);
@@ -25,7 +25,7 @@ export type TimelineTypeEnum = typeof TimelineType.enum;
 export const TimelineTypeEnum = TimelineType.enum;
 
 /**
- * The type of data provider to create. Valid values are `default` and `template`.
+ * The type of data provider.
  */
 export type DataProviderType = z.infer<typeof DataProviderType>;
 export const DataProviderType = z.enum(['default', 'template']);
@@ -87,6 +87,9 @@ export const DataProviderResult = z.object({
   type: DataProviderType.nullable().optional(),
 });
 
+/**
+ * Identifies the available row renderers
+ */
 export type RowRendererId = z.infer<typeof RowRendererId>;
 export const RowRendererId = z.enum([
   'alert',
@@ -111,6 +114,9 @@ export const RowRendererId = z.enum([
 export type RowRendererIdEnum = typeof RowRendererId.enum;
 export const RowRendererIdEnum = RowRendererId.enum;
 
+/**
+ * Indicates when and who marked a Timeline as a favorite.
+ */
 export type FavoriteTimelineResult = z.infer<typeof FavoriteTimelineResult>;
 export const FavoriteTimelineResult = z.object({
   fullName: z.string().nullable().optional(),
@@ -144,6 +150,9 @@ export const FilterTimelineResult = z.object({
   script: z.string().nullable().optional(),
 });
 
+/**
+ * KQL bar query.
+ */
 export type SerializedFilterQueryResult = z.infer<typeof SerializedFilterQueryResult>;
 export const SerializedFilterQueryResult = z.object({
   filterQuery: z
@@ -161,6 +170,9 @@ export const SerializedFilterQueryResult = z.object({
     .optional(),
 });
 
+/**
+ * Object indicating how rows are sorted in the Timeline's grid
+ */
 export type SortObject = z.infer<typeof SortObject>;
 export const SortObject = z.object({
   columnId: z.string().nullable().optional(),
@@ -171,13 +183,39 @@ export const SortObject = z.object({
 export type Sort = z.infer<typeof Sort>;
 export const Sort = z.union([SortObject, z.array(SortObject)]);
 
+/**
+ * The status of the Timeline.
+ */
+export type TimelineStatus = z.infer<typeof TimelineStatus>;
+export const TimelineStatus = z.enum(['active', 'draft', 'immutable']);
+export type TimelineStatusEnum = typeof TimelineStatus.enum;
+export const TimelineStatusEnum = TimelineStatus.enum;
+
 export type SavedTimeline = z.infer<typeof SavedTimeline>;
 export const SavedTimeline = z.object({
+  /**
+   * The Timeline's columns
+   */
   columns: z.array(ColumnHeaderResult).nullable().optional(),
+  /**
+   * The time the Timeline was created, using a 13-digit Epoch timestamp.
+   */
   created: z.number().nullable().optional(),
+  /**
+   * The user who created the Timeline.
+   */
   createdBy: z.string().nullable().optional(),
+  /**
+   * Object containing query clauses
+   */
   dataProviders: z.array(DataProviderResult).nullable().optional(),
+  /**
+   * ID of the Timeline's Data View
+   */
   dataViewId: z.string().nullable().optional(),
+  /**
+   * The Timeline's search period.
+   */
   dateRange: z
     .object({
       end: z.union([z.string().nullable(), z.number().nullable()]).optional(),
@@ -185,7 +223,13 @@ export const SavedTimeline = z.object({
     })
     .nullable()
     .optional(),
+  /**
+   * The Timeline's description
+   */
   description: z.string().nullable().optional(),
+  /**
+   * EQL query that is used in the correlation tab
+   */
   eqlOptions: z
     .object({
       eventCategoryField: z.string().nullable().optional(),
@@ -196,66 +240,175 @@ export const SavedTimeline = z.object({
     })
     .nullable()
     .optional(),
+  /**
+   * Event types displayed in the Timeline
+   */
   eventType: z.string().nullable().optional(),
+  /**
+   * A list of row renderers that should not be used when in `Event renderers` mode
+   */
   excludedRowRendererIds: z.array(RowRendererId).nullable().optional(),
   favorite: z.array(FavoriteTimelineResult).nullable().optional(),
+  /**
+   * A list of filters that should be applied to the query
+   */
   filters: z.array(FilterTimelineResult).nullable().optional(),
+  /**
+   * Indicates whether the KQL bar filters the query results or searches for additional results, where:
+   * `filter`: filters query results
+   * `search`: displays additional search results
+   */
   kqlMode: z.string().nullable().optional(),
   kqlQuery: SerializedFilterQueryResult.nullable().optional(),
+  /**
+   * A list of index names to use in the query (e.g. when the default data view has been modified)
+   */
   indexNames: z.array(z.string()).nullable().optional(),
+  /**
+   * The ID of the saved search that is used in the ES|QL tab
+   */
   savedSearchId: z.string().nullable().optional(),
+  /**
+   * The ID of the saved query that might be used in the Query tab
+   */
   savedQueryId: z.string().nullable().optional(),
   sort: Sort.nullable().optional(),
-  status: z.enum(['active', 'draft', 'immutable']).nullable().optional(),
+  status: TimelineStatus.nullable().optional(),
+  /**
+   * The Timeline's title.
+   */
   title: z.string().nullable().optional(),
+  /**
+   * A unique ID (UUID) for Timeline templates. For Timelines, the value is `null`.
+   */
   templateTimelineId: z.string().nullable().optional(),
+  /**
+   * Timeline template version number. For Timelines, the value is `null`.
+   */
   templateTimelineVersion: z.number().nullable().optional(),
   timelineType: TimelineType.nullable().optional(),
+  /**
+   * The last time the Timeline was updated, using a 13-digit Epoch timestamp
+   */
   updated: z.number().nullable().optional(),
+  /**
+   * The user who last updated the Timeline
+   */
   updatedBy: z.string().nullable().optional(),
 });
 
 export type SavedTimelineWithSavedObjectId = z.infer<typeof SavedTimelineWithSavedObjectId>;
 export const SavedTimelineWithSavedObjectId = SavedTimeline.merge(
   z.object({
+    /**
+     * The `savedObjectId` of the Timeline or Timeline template
+     */
     savedObjectId: z.string(),
+    /**
+     * The version of the Timeline or Timeline template
+     */
     version: z.string(),
   })
 );
 
-export type BareNote = z.infer<typeof BareNote>;
+export type NoteCreatedAndUpdatedMetadata = z.infer<typeof NoteCreatedAndUpdatedMetadata>;
-export const BareNote = z.object({
+export const NoteCreatedAndUpdatedMetadata = z.object({
-  eventId: z.string().nullable().optional(),
+  /**
-  note: z.string().nullable().optional(),
+   * The time the note was created, using a 13-digit Epoch timestamp.
-  timelineId: z.string(),
+   */
   created: z.number().nullable().optional(),
+  /**
+   * The user who created the note.
+   */
   createdBy: z.string().nullable().optional(),
+  /**
+   * The last time the note was updated, using a 13-digit Epoch timestamp
+   */
   updated: z.number().nullable().optional(),
+  /**
+   * The user who last updated the note
+   */
   updatedBy: z.string().nullable().optional(),
 });
 
+export type BareNote = z.infer<typeof BareNote>;
+export const BareNote = NoteCreatedAndUpdatedMetadata.merge(
+  z.object({
+    /**
+     * The `_id` of the associated event for this note.
+     */
+    eventId: z.string().nullable().optional(),
+    /**
+     * The text of the note
+     */
+    note: z.string().nullable().optional(),
+    /**
+     * The `savedObjectId` of the Timeline that this note is associated with
+     */
+    timelineId: z.string(),
+  })
+);
+
 export type Note = z.infer<typeof Note>;
 export const Note = BareNote.merge(
   z.object({
+    /**
+     * The `savedObjectId` of the note
+     */
     noteId: z.string(),
+    /**
+     * The version of the note
+     */
     version: z.string(),
   })
 );
 
-export type BarePinnedEvent = z.infer<typeof BarePinnedEvent>;
+export type PinnedEventCreatedAndUpdatedMetadata = z.infer<
-export const BarePinnedEvent = z.object({
+  typeof PinnedEventCreatedAndUpdatedMetadata
-  eventId: z.string(),
+>;
-  timelineId: z.string(),
+export const PinnedEventCreatedAndUpdatedMetadata = z.object({
+  /**
+   * The time the pinned event was created, using a 13-digit Epoch timestamp.
+   */
   created: z.number().nullable().optional(),
+  /**
+   * The user who created the pinned event.
+   */
   createdBy: z.string().nullable().optional(),
+  /**
+   * The last time the pinned event was updated, using a 13-digit Epoch timestamp
+   */
   updated: z.number().nullable().optional(),
+  /**
+   * The user who last updated the pinned event
+   */
   updatedBy: z.string().nullable().optional(),
 });
 
+export type BarePinnedEvent = z.infer<typeof BarePinnedEvent>;
+export const BarePinnedEvent = PinnedEventCreatedAndUpdatedMetadata.merge(
+  z.object({
+    /**
+     * The `_id` of the associated event for this pinned event.
+     */
+    eventId: z.string(),
+    /**
+     * The `savedObjectId` of the timeline that this pinned event is associated with
+     */
+    timelineId: z.string(),
+  })
+);
+
 export type PinnedEvent = z.infer<typeof PinnedEvent>;
 export const PinnedEvent = BarePinnedEvent.merge(
   z.object({
+    /**
+     * The `savedObjectId` of this pinned event
+     */
     pinnedEventId: z.string(),
+    /**
+     * The version of this pinned event
+     */
     version: z.string(),
   })
 );
@@ -263,10 +416,25 @@ export const PinnedEvent = BarePinnedEvent.merge(
 export type TimelineResponse = z.infer<typeof TimelineResponse>;
 export const TimelineResponse = SavedTimeline.merge(SavedTimelineWithSavedObjectId).merge(
   z.object({
+    /**
+     * A list of all the notes that are associated to this Timeline.
+     */
     eventIdToNoteIds: z.array(Note).nullable().optional(),
+    /**
+     * A list of all the notes that are associated to this Timeline.
+     */
     notes: z.array(Note).nullable().optional(),
+    /**
+     * A list of all the ids of notes that are associated to this Timeline.
+     */
     noteIds: z.array(z.string()).nullable().optional(),
+    /**
+     * A list of all the ids of pinned events that are associated to this Timeline.
+     */
     pinnedEventIds: z.array(z.string()).nullable().optional(),
+    /**
+     * A list of all the pinned events that are associated to this Timeline.
+     */
     pinnedEventsSaveObject: z.array(PinnedEvent).nullable().optional(),
   })
 );
@@ -319,27 +487,22 @@ export type PersistTimelineResponse = z.infer<typeof PersistTimelineResponse>;
 export const PersistTimelineResponse = TimelineResponse;
 
 export type BareNoteWithoutExternalRefs = z.infer<typeof BareNoteWithoutExternalRefs>;
-export const BareNoteWithoutExternalRefs = z.object({
+export const BareNoteWithoutExternalRefs = NoteCreatedAndUpdatedMetadata.merge(
-  eventId: z.string().nullable().optional(),
+  z.object({
-  note: z.string().nullable().optional(),
+    /**
-  timelineId: z.string().nullable().optional(),
+     * The `_id` of the associated event for this note.
-  created: z.number().nullable().optional(),
+     */
-  createdBy: z.string().nullable().optional(),
+    eventId: z.string().nullable().optional(),
-  updated: z.number().nullable().optional(),
+    /**
-  updatedBy: z.string().nullable().optional(),
+     * The text of the note
-});
+     */
-
+    note: z.string().nullable().optional(),
-export type GlobalNote = z.infer<typeof GlobalNote>;
+    /**
-export const GlobalNote = z.object({
+     * The `savedObjectId` of the timeline that this note is associated with
-  noteId: z.string().optional(),
+     */
-  version: z.string().optional(),
+    timelineId: z.string().optional(),
-  note: z.string().optional(),
+  })
-  timelineId: z.string().optional(),
+);
-  created: z.number().optional(),
-  createdBy: z.string().optional(),
-  updated: z.number().optional(),
-  updatedBy: z.string().optional(),
-});
 
 /**
  * The field to sort the timelines by.
@@ -354,14 +517,6 @@ export const SortDirection = z.enum(['asc', 'desc']);
 export type SortDirectionEnum = typeof SortDirection.enum;
 export const SortDirectionEnum = SortDirection.enum;
 
-/**
- * The status of the timeline. Valid values are `active`, `draft`, and `immutable`.
- */
-export type TimelineStatus = z.infer<typeof TimelineStatus>;
-export const TimelineStatus = z.enum(['active', 'draft', 'immutable']);
-export type TimelineStatusEnum = typeof TimelineStatus.enum;
-export const TimelineStatusEnum = TimelineStatus.enum;
-
 export type ImportTimelines = z.infer<typeof ImportTimelines>;
 export const ImportTimelines = SavedTimeline.merge(
   z.object({
@@ -375,17 +530,44 @@ export const ImportTimelines = SavedTimeline.merge(
 
 export type ImportTimelineResult = z.infer<typeof ImportTimelineResult>;
 export const ImportTimelineResult = z.object({
+  /**
+   * Indicates whether any of the Timelines were successfully imports
+   */
   success: z.boolean().optional(),
+  /**
+   * The amount of successfully imported/updated Timelines
+   */
   success_count: z.number().optional(),
+  /**
+   * The amount of successfully installed Timelines
+   */
   timelines_installed: z.number().optional(),
+  /**
+   * The amount of successfully updated Timelines
+   */
   timelines_updated: z.number().optional(),
+  /**
+   * The list of failed Timeline imports
+   */
   errors: z
     .array(
       z.object({
+        /**
+         * The ID of the timeline that failed to import
+         */
         id: z.string().optional(),
+        /**
+         * The error containing the reason why the timeline could not be imported
+         */
         error: z
           .object({
+            /**
+             * The reason why the timeline could not be imported
+             */
             message: z.string().optional(),
+            /**
+             * The HTTP status code of the error
+             */
             status_code: z.number().optional(),
           })
           .optional(),

x-pack/solutions/security/plugins/security_solution/common/api/timeline/model/components.schema.yaml

@@ -12,7 +12,7 @@ components:
         - template
       # enum default value is temporarily unsupported by the code generator
       # default: default
-      description: The type of timeline to create. Valid values are `default` and `template`.
+      description: The type of Timeline.
     DataProviderType:
       type: string
       enum:
@@ -20,7 +20,7 @@ components:
         - template
       # enum default value is temporarily unsupported by the code generator
       # default: default
-      description: The type of data provider to create. Valid values are `default` and `template`.
+      description: The type of data provider.
     TemplateTimelineType:
       type: string
       enum:
@@ -35,23 +35,46 @@ components:
           nullable: true
           items:
             $ref: '#/components/schemas/ColumnHeaderResult'
+          description: The Timeline's columns
+          example:
+            - columnHeaderType: 'not-filtered'
+              id: '@timestamp'
+            - columnHeaderType: 'not-filtered'
+              id: 'event.category'
         created:
           type: number
           nullable: true
+          description: The time the Timeline was created, using a 13-digit Epoch timestamp.
+          example: 1587468588922
         createdBy:
           type: string
           nullable: true
+          description: The user who created the Timeline.
+          example: casetester
         dataProviders:
           type: array
           nullable: true
+          description: Object containing query clauses
           items:
             $ref: '#/components/schemas/DataProviderResult'
+          example:
+            - enabled: true
+              excluded: false
+              id: id-d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b
+              name: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b
+              queryMatch:
+                field: _id,
+                value: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b,
+                operator: ':'
         dataViewId:
           type: string
           nullable: true
+          description: ID of the Timeline's Data View
+          example: security-solution-default
         dateRange:
           type: object
           nullable: true
+          description: The Timeline's search period.
           properties:
             end:
               oneOf:
@@ -65,12 +88,23 @@ components:
                   nullable: true
                 - type: number
                   nullable: true
+          example:
+            start: 1587370079200
+            end: 1587456479201
         description:
           type: string
           nullable: true
+          description: The Timeline's description
+          example: Investigating exposure of CVE XYZ
         eqlOptions:
           type: object
           nullable: true
+          description: EQL query that is used in the correlation tab
+          example:
+            eventCategoryField: 'event.category'
+            query: 'sequence\n[process where process.name == "sudo"]\n[any where true]'
+            size: 100
+            timestampField: '@timestamp'
           properties:
             eventCategoryField:
               type: string
@@ -93,9 +127,13 @@ components:
         eventType:
           type: string
           nullable: true
+          description: Event types displayed in the Timeline
+          example: all
+          deprecated: true
         excludedRowRendererIds:
           type: array
           nullable: true
+          description: A list of row renderers that should not be used when in `Event renderers` mode
           items:
             $ref: '#/components/schemas/RowRendererId'
         favorite:
@@ -106,53 +144,72 @@ components:
         filters:
           type: array
           nullable: true
+          description: A list of filters that should be applied to the query
           items:
             $ref: '#/components/schemas/FilterTimelineResult'
         kqlMode:
           type: string
           nullable: true
+          example: search
+          description: >-
+            Indicates whether the KQL bar filters the query results or searches for additional results, where:
+              * `filter`: filters query results
+              * `search`: displays additional search results
         kqlQuery:
           nullable: true
           $ref: '#/components/schemas/SerializedFilterQueryResult'
         indexNames:
           type: array
           nullable: true
+          description: A list of index names to use in the query (e.g. when the default data view has been modified)
+          example:
+            - '.logs*'
           items:
             type: string
         savedSearchId:
           type: string
+          description: The ID of the saved search that is used in the ES|QL tab
           nullable: true
+          example: '6ce1b592-84e3-4b4a-9552-f189d4b82075'
         savedQueryId:
           type: string
           nullable: true
+          description: The ID of the saved query that might be used in the Query tab
+          example: c7b16904-02d7-4f32-b8f2-cc20f9625d6e
         sort:
           nullable: true
           $ref: '#/components/schemas/Sort'
         status:
-          type: string
           nullable: true
-          enum:
+          $ref: '#/components/schemas/TimelineStatus'
-            - active
-            - draft
-            - immutable
         title:
           type: string
           nullable: true
+          description: "The Timeline's title."
+          example: CVE XYZ investigation
         templateTimelineId:
           type: string
           nullable: true
+          description: A unique ID (UUID) for Timeline templates. For Timelines, the value is `null`.
+          example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
         templateTimelineVersion:
           type: number
           nullable: true
+          description: Timeline template version number. For Timelines, the value is `null`.
+          example: 12
         timelineType:
           nullable: true
           $ref: '#/components/schemas/TimelineType'
         updated:
           type: number
           nullable: true
+          description: The last time the Timeline was updated, using a 13-digit Epoch timestamp
+          example: 1741344876825
         updatedBy:
           type: string
           nullable: true
+          description: The user who last updated the Timeline
+          example: casetester
     SavedTimelineWithSavedObjectId:
       allOf:
         - $ref: '#/components/schemas/SavedTimeline'
@@ -161,8 +218,12 @@ components:
           properties:
             savedObjectId:
               type: string
+              example: '15c1929b-0af7-42bd-85a8-56e234cc7c4e'
+              description: The `savedObjectId` of the Timeline or Timeline template
             version:
               type: string
+              example: 'WzE0LDFd'
+              description: The version of the Timeline or Timeline template
     TimelineResponse:
       allOf:
         - $ref: '#/components/schemas/SavedTimeline'
@@ -172,26 +233,35 @@ components:
             eventIdToNoteIds:
               type: array
               nullable: true
+              description: A list of all the notes that are associated to this Timeline.
               items:
                 $ref: '#/components/schemas/Note'
             notes:
               type: array
               nullable: true
+              description: A list of all the notes that are associated to this Timeline.
               items:
                 $ref: '#/components/schemas/Note'
             noteIds:
               type: array
               nullable: true
+              description: A list of all the ids of notes that are associated to this Timeline.
               items:
                 type: string
+              example:
+                - 709f99c6-89b6-4953-9160-35945c8e174e
             pinnedEventIds:
               type: array
               nullable: true
+              description: A list of all the ids of pinned events that are associated to this Timeline.
               items:
                 type: string
+              example:
+                - 983f99c6-89b6-4953-9160-35945c8a194f
             pinnedEventsSaveObject:
               type: array
               nullable: true
+              description: A list of all the pinned events that are associated to this Timeline.
               items:
                 $ref: '#/components/schemas/PinnedEvent'
     ResolvedTimeline:
@@ -353,54 +423,68 @@ components:
         type:
           $ref: '#/components/schemas/DataProviderType'
           nullable: true
+    NoteCreatedAndUpdatedMetadata:
+      type: object
+      properties:
+        created:
+          type: number
+          nullable: true
+          description: The time the note was created, using a 13-digit Epoch timestamp.
+          example: 1587468588922
+        createdBy:
+          type: string
+          nullable: true
+          description: The user who created the note.
+          example: casetester
+        updated:
+          type: number
+          nullable: true
+          description: The last time the note was updated, using a 13-digit Epoch timestamp
+          example: 1741344876825
+        updatedBy:
+          type: string
+          nullable: true
+          description: The user who last updated the note
+          example: casetester
     BareNoteWithoutExternalRefs:
-      type: object
+      allOf:
-      properties:
+        - $ref: '#/components/schemas/NoteCreatedAndUpdatedMetadata'
-        eventId:
+        - type: object
-          type: string
+          properties:
-          nullable: true
+            eventId:
-        note:
+              type: string
-          type: string
+              nullable: true
-          nullable: true
+              description: The `_id` of the associated event for this note.
-        timelineId:
+              example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
-          type: string
+            note:
-          nullable: true
+              type: string
-        created:
+              nullable: true
-          type: number
+              description: The text of the note
-          nullable: true
+              example: This is an example text
-        createdBy:
+            timelineId:
-          type: string
+              type: string
-          nullable: true
+              description: The `savedObjectId` of the timeline that this note is associated with
-        updated:
+              example: '15c1929b-0af7-42bd-85a8-56e234cc7c4e'
-          type: number
-          nullable: true
-        updatedBy:
-          type: string
-          nullable: true
     BareNote:
-      type: object
+      allOf:
-      required: [timelineId]
+        - $ref: '#/components/schemas/NoteCreatedAndUpdatedMetadata'
-      properties:
+        - type: object
-        eventId:
+          required: [timelineId]
-          type: string
+          properties:
-          nullable: true
+            eventId:
-        note:
+              type: string
-          type: string
+              nullable: true
-          nullable: true
+              description: The `_id` of the associated event for this note.
-        timelineId:
+              example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
-          type: string
+            note:
-        created:
+              type: string
-          type: number
+              nullable: true
-          nullable: true
+              description: The text of the note
-        createdBy:
+              example: This is an example text
-          type: string
+            timelineId:
-          nullable: true
+              type: string
-        updated:
+              description: The `savedObjectId` of the Timeline that this note is associated with
-          type: number
+              example: '15c1929b-0af7-42bd-85a8-56e234cc7c4e'
-          nullable: true
-        updatedBy:
-          type: string
-          nullable: true
     Note:
       allOf:
         - $ref: '#/components/schemas/BareNote'
@@ -409,27 +493,12 @@ components:
           properties:
             noteId:
               type: string
+              description: The `savedObjectId` of the note
+              example: 709f99c6-89b6-4953-9160-35945c8e174e
             version:
               type: string
-    GlobalNote:
+              description: The version of the note
-      type: object
+              example: WzQ2LDFd
-      properties:
-        noteId:
-          type: string
-        version:
-          type: string
-        note:
-          type: string
-        timelineId:
-          type: string
-        created:
-          type: number
-        createdBy:
-          type: string
-        updated:
-          type: number
-        updatedBy:
-          type: string
     RowRendererId:
       type: string
       enum:
@@ -451,8 +520,10 @@ components:
         - system_socket
         - threat_match
         - zeek
+      description: Identifies the available row renderers
     FavoriteTimelineResult:
       type: object
+      description: Indicates when and who marked a Timeline as a favorite.
       properties:
         fullName:
           type: string
@@ -463,6 +534,9 @@ components:
         favoriteDate:
           type: number
           nullable: true
+      example:
+        userName: elastic
+        favoriteDate: 1741337636741
     FilterTimelineResult:
       type: object
       properties:
@@ -521,8 +595,19 @@ components:
         script:
           type: string
           nullable: true
+      example:
+        query: '{"exists":{"field":"@timestamp"}}'
+        meta:
+          alias: 'Custom filter name'
+          disabled: false
+          index: '.alerts-security.alerts-default,logs-*'
+          key: '@timestamp'
+          negate: false,
+          type: exists
+          value: exists
     SerializedFilterQueryResult:
       type: object
+      description: KQL bar query.
       properties:
         filterQuery:
           type: object
@@ -541,26 +626,49 @@ components:
             serializedQuery:
               type: string
               nullable: true
-    BarePinnedEvent:
+      example:
+        filterQuery:
+        kuery:
+          kind: kuery
+          expression: '_id : *'
+        serializedQuery: '{"bool":{"should":[{"exists":{"field":"_id"}}],"minimum_should_match":1}}'
+    PinnedEventCreatedAndUpdatedMetadata:
       type: object
-      required: [eventId, timelineId]
       properties:
-        eventId:
-          type: string
-        timelineId:
-          type: string
         created:
           type: number
           nullable: true
+          description: The time the pinned event was created, using a 13-digit Epoch timestamp.
+          example: 1587468588922
         createdBy:
           type: string
           nullable: true
+          description: The user who created the pinned event.
+          example: casetester
         updated:
           type: number
           nullable: true
+          description: The last time the pinned event was updated, using a 13-digit Epoch timestamp
+          example: 1741344876825
         updatedBy:
           type: string
           nullable: true
+          description: The user who last updated the pinned event
+          example: casetester
+    BarePinnedEvent:
+      allOf:
+        - $ref: '#/components/schemas/PinnedEventCreatedAndUpdatedMetadata'
+        - type: object
+          required: [eventId, timelineId]
+          properties:
+            eventId:
+              type: string
+              description: The `_id` of the associated event for this pinned event.
+              example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
+            timelineId:
+              type: string
+              description: The `savedObjectId` of the timeline that this pinned event is associated with
+              example: '15c1929b-0af7-42bd-85a8-56e234cc7c4e'
     PinnedEvent:
       allOf:
         - $ref: '#/components/schemas/BarePinnedEvent'
@@ -569,8 +677,12 @@ components:
           properties:
             pinnedEventId:
               type: string
+              description: The `savedObjectId` of this pinned event
+              example: '10r1929b-0af7-42bd-85a8-56e234f98h2f3'
             version:
               type: string
+              description: The version of this pinned event
+              example: WzQ2LDFe
     Sort:
       oneOf:
         - $ref: '#/components/schemas/SortObject'
@@ -589,6 +701,10 @@ components:
         sortDirection:
           type: string
           nullable: true
+      description: Object indicating how rows are sorted in the Timeline's grid
+      example:
+        sortDirection: desc
+        columnId: '@timestamp'
     SortFieldTimeline:
       type: string
       description: The field to sort the timelines by.
@@ -604,13 +720,13 @@ components:
         - desc
     TimelineStatus:
       type: string
+      description: The status of the Timeline.
       enum:
         - active
         - draft
         - immutable
       # enum default value is temporarily unsupported by the code generator
       # default: draft
-      description: The status of the timeline. Valid values are `active`, `draft`, and `immutable`.
     ImportTimelines:
       allOf:
         - $ref: '#/components/schemas/SavedTimeline'
@@ -678,26 +794,41 @@ components:
       properties:
         success:
           type: boolean
+          description: Indicates whether any of the Timelines were successfully imports
         success_count:
           type: number
+          description: The amount of successfully imported/updated Timelines
+          example: 99
         timelines_installed:
           type: number
+          description: The amount of successfully installed Timelines
+          example: 80
         timelines_updated:
           type: number
+          description: The amount of successfully updated Timelines
+          example: 19
         errors:
+          description: The list of failed Timeline imports
           type: array
           items:
             type: object
             properties:
               id:
                 type: string
+                description: The ID of the timeline that failed to import
+                example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
               error:
                 type: object
+                description: The error containing the reason why the timeline could not be imported
                 properties:
                   message:
                     type: string
+                    description: The reason why the timeline could not be imported
+                    example: Malformed JSON
                   status_code:
                     type: number
+                    description: The HTTP status code of the error
+                    example: 400
     TimelineErrorResponse:
       oneOf:
         - type: object

x-pack/solutions/security/plugins/security_solution/common/api/timeline/patch_timelines/patch_timeline_route.gen.ts

@@ -20,8 +20,17 @@ import { SavedTimeline, PersistTimelineResponse } from '../model/components.gen'
 
 export type PatchTimelineRequestBody = z.infer<typeof PatchTimelineRequestBody>;
 export const PatchTimelineRequestBody = z.object({
+  /**
+   * The `savedObjectId` of the Timeline or Timeline template that you’re updating.
+   */
   timelineId: z.string().nullable(),
+  /**
+   * The version of the Timeline or Timeline template that you’re updating.
+   */
   version: z.string().nullable(),
+  /**
+   * The timeline object of the Timeline or Timeline template that you’re updating.
+   */
   timeline: SavedTimeline,
 });
 export type PatchTimelineRequestBodyInput = z.input<typeof PatchTimelineRequestBody>;

x-pack/solutions/security/plugins/security_solution/common/api/timeline/patch_timelines/patch_timeline_route.schema.yaml

@@ -24,20 +24,25 @@ paths:
                 timelineId:
                   type: string
                   nullable: true
+                  example: '15c1929b-0af7-42bd-85a8-56e234cc7c4e'
+                  description: The `savedObjectId` of the Timeline or Timeline template that you’re updating.
                 version:
                   type: string
                   nullable: true
+                  example: 'WzE0LDFd'
+                  description: The version of the Timeline or Timeline template that you’re updating.
                 timeline:
                   $ref: '../model/components.schema.yaml#/components/schemas/SavedTimeline'
+                  description: The timeline object of the Timeline or Timeline template that you’re updating.
       responses:
         '200':
-          description: Indicates that the draft Timeline was successfully created. In the event the user already has a draft Timeline, the existing draft Timeline is cleared and returned.
+          description: Indicates that the Timeline was successfully updated.
           content:
             application/json:
               schema:
                 $ref: '../model/components.schema.yaml#/components/schemas/PersistTimelineResponse'
         '405':
-          description: Indicates that the user does not have the required access to create a draft Timeline.
+          description: Indicates that the user does not have the required access to create a Timeline.
           content:
             application/json:
               schema:
@@ -45,5 +50,8 @@ paths:
                 properties:
                   body:
                     type: string
+                    description: The error message
+                    example: update timeline error
                   statusCode:
                     type: number
+                    example: 405

x-pack/solutions/security/plugins/security_solution/common/api/timeline/persist_note/persist_note_route.gen.ts

@@ -25,13 +25,18 @@ export const ResponseNote = z.object({
 
 export type PersistNoteRouteRequestBody = z.infer<typeof PersistNoteRouteRequestBody>;
 export const PersistNoteRouteRequestBody = z.object({
+  /**
+   * The note to add or update.
+   */
   note: BareNote,
-  overrideOwner: z.boolean().nullable().optional(),
+  /**
+   * The `savedObjectId` of the note
+   */
   noteId: z.string().nullable().optional(),
+  /**
+   * The version of the note
+   */
   version: z.string().nullable().optional(),
-  eventIngested: z.string().nullable().optional(),
-  eventTimestamp: z.string().nullable().optional(),
-  eventDataView: z.string().nullable().optional(),
 });
 export type PersistNoteRouteRequestBodyInput = z.input<typeof PersistNoteRouteRequestBody>;
 

x-pack/solutions/security/plugins/security_solution/common/api/timeline/persist_note/persist_note_route.schema.yaml

@@ -26,24 +26,17 @@ paths:
               properties:
                 note:
                   $ref: '../model/components.schema.yaml#/components/schemas/BareNote'
-                overrideOwner:
+                  description: The note to add or update.
-                  type: boolean
-                  nullable: true
                 noteId:
                   type: string
                   nullable: true
+                  description: The `savedObjectId` of the note
+                  example: 709f99c6-89b6-4953-9160-35945c8e174e
                 version:
                   type: string
                   nullable: true
-                eventIngested:
+                  description: The version of the note
-                  type: string
+                  example: WzQ2LDFd
-                  nullable: true
-                eventTimestamp:
-                  type: string
-                  nullable: true
-                eventDataView:
-                  type: string
-                  nullable: true
       responses:
         '200':
           description: Indicates the note was successfully created.

x-pack/solutions/security/plugins/security_solution/common/api/timeline/pinned_events/pinned_events_route.gen.ts

@@ -10,7 +10,7 @@
  * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator.
  *
  * info:
- *   title: Elastic Security - Timeline - Pinned Event API
+ *   title: Elastic Security - Timeline - pinned event API
  *   version: 2023-10-31
  */
 
@@ -22,15 +22,27 @@ export type PersistPinnedEventResponse = z.infer<typeof PersistPinnedEventRespon
 export const PersistPinnedEventResponse = z.union([
   PinnedEvent,
   z.object({
+    /**
+     * Indicates whether the event was successfully unpinned
+     */
     unpinned: z.boolean(),
   }),
 ]);
 
 export type PersistPinnedEventRouteRequestBody = z.infer<typeof PersistPinnedEventRouteRequestBody>;
 export const PersistPinnedEventRouteRequestBody = z.object({
+  /**
+   * The `_id` of the associated event for this pinned event.
+   */
   eventId: z.string(),
-  pinnedEventId: z.string().nullable().optional(),
+  /**
+   * The `savedObjectId` of the timeline that you want this pinned event unpinned from.
+   */
   timelineId: z.string(),
+  /**
+   * The `savedObjectId` of the pinned event you want to unpin.
+   */
+  pinnedEventId: z.string().nullable().optional(),
 });
 export type PersistPinnedEventRouteRequestBodyInput = z.input<
   typeof PersistPinnedEventRouteRequestBody

x-pack/solutions/security/plugins/security_solution/common/api/timeline/pinned_events/pinned_events_route.schema.yaml

@@ -1,6 +1,6 @@
 openapi: 3.0.0
 info:
-  title: Elastic Security - Timeline - Pinned Event API
+  title: Elastic Security - Timeline - pinned event API
   version: '2023-10-31'
 externalDocs:
   url: https://www.elastic.co/guide/en/security/current/_pin_an_event_to_an_existing_timeline.html
@@ -11,12 +11,12 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: PersistPinnedEventRoute
-      summary: Pin an event
+      summary: Pin/unpin an event
-      description: Pin an event to an existing Timeline.
+      description: Pin/unpin an event to/from an existing Timeline.
       tags:
         - access:securitySolution
       requestBody:
-        description: The pinned event to add or update, along with additional metadata.
+        description: The pinned event to add or unpin, along with additional metadata.
         required: true
         content:
           application/json:
@@ -26,14 +26,20 @@ paths:
               properties:
                 eventId:
                   type: string
+                  description: The `_id` of the associated event for this pinned event.
+                  example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
+                timelineId:
+                  type: string
+                  description: The `savedObjectId` of the timeline that you want this pinned event unpinned from.
+                  example: '15c1929b-0af7-42bd-85a8-56e234cc7c4e'
                 pinnedEventId:
                   type: string
                   nullable: true
-                timelineId:
+                  description: The `savedObjectId` of the pinned event you want to unpin.
-                  type: string
+                  example: '10r1929b-0af7-42bd-85a8-56e234f98h2f3'
       responses:
         '200':
-          description: Indicates the event was successfully pinned to the Timeline.
+          description: Indicates the event was successfully pinned to or unpinned from the Timeline.
           content:
             application/json:
               schema:
@@ -49,3 +55,4 @@ components:
           properties:
             unpinned:
               type: boolean
+              description: Indicates whether the event was successfully unpinned

x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_timeline_api_2023_10_31.bundled.schema.yaml

@@ -119,24 +119,17 @@ paths:
             schema:
               type: object
               properties:
-                eventDataView:
-                  nullable: true
-                  type: string
-                eventIngested:
-                  nullable: true
-                  type: string
-                eventTimestamp:
-                  nullable: true
-                  type: string
                 note:
                   $ref: '#/components/schemas/BareNote'
+                  description: The note to add or update.
                 noteId:
+                  description: The `savedObjectId` of the note
+                  example: 709f99c6-89b6-4953-9160-35945c8e174e
                   nullable: true
                   type: string
-                overrideOwner:
-                  nullable: true
-                  type: boolean
                 version:
+                  description: The version of the note
+                  example: WzQ2LDFd
                   nullable: true
                   type: string
               required:
@@ -156,7 +149,7 @@ paths:
         - access:securitySolution
   /api/pinned_event:
     patch:
-      description: Pin an event to an existing Timeline.
+      description: Pin/unpin an event to/from an existing Timeline.
       operationId: PersistPinnedEventRoute
       requestBody:
         content:
@@ -165,16 +158,24 @@ paths:
               type: object
               properties:
                 eventId:
+                  description: The `_id` of the associated event for this pinned event.
+                  example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
                   type: string
                 pinnedEventId:
+                  description: The `savedObjectId` of the pinned event you want to unpin.
+                  example: 10r1929b-0af7-42bd-85a8-56e234f98h2f3
                   nullable: true
                   type: string
                 timelineId:
+                  description: >-
+                    The `savedObjectId` of the timeline that you want this
+                    pinned event unpinned from.
+                  example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
                   type: string
               required:
                 - eventId
                 - timelineId
-        description: The pinned event to add or update, along with additional metadata.
+        description: The pinned event to add or unpin, along with additional metadata.
         required: true
       responses:
         '200':
@@ -182,8 +183,10 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/PersistPinnedEventResponse'
-          description: Indicates the event was successfully pinned to the Timeline.
+          description: >-
-      summary: Pin an event
+            Indicates the event was successfully pinned to or unpinned from the
+            Timeline.
+      summary: Pin/unpin an event
       tags:
         - Security Timeline API
         - access:securitySolution
@@ -198,13 +201,21 @@ paths:
               type: object
               properties:
                 savedObjectIds:
+                  description: >-
+                    The list of IDs of the Timelines or Timeline templates to
+                    delete
+                  example:
+                    - 15c1929b-0af7-42bd-85a8-56e234cc7c4e
                   items:
                     type: string
                   type: array
                 searchIds:
                   description: >-
-                    Saved search ids that should be deleted alongside the
+                    Saved search IDs that should be deleted alongside the
                     timelines
+                  example:
+                    - 23f3-43g34g322-e5g5hrh6h-45454
+                    - 6ce1b592-84e3-4b4a-9552-f189d4b82075
                   items:
                     type: string
                   type: array
@@ -223,12 +234,12 @@ paths:
       description: Get the details of an existing saved Timeline or Timeline template.
       operationId: GetTimeline
       parameters:
-        - description: The ID of the template timeline to retrieve
+        - description: The `savedObjectId` of the template timeline to retrieve
           in: query
           name: template_timeline_id
           schema:
             type: string
-        - description: The ID of the Timeline to retrieve.
+        - description: The `savedObjectId` of the Timeline to retrieve.
           in: query
           name: id
           schema:
@@ -258,10 +269,21 @@ paths:
               properties:
                 timeline:
                   $ref: '#/components/schemas/SavedTimeline'
+                  description: >-
+                    The timeline object of the Timeline or Timeline template
+                    that you’re updating.
                 timelineId:
+                  description: >-
+                    The `savedObjectId` of the Timeline or Timeline template
+                    that you’re updating.
+                  example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
                   nullable: true
                   type: string
                 version:
+                  description: >-
+                    The version of the Timeline or Timeline template that you’re
+                    updating.
+                  example: WzE0LDFd
                   nullable: true
                   type: string
               required:
@@ -276,10 +298,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/PersistTimelineResponse'
-          description: >-
+          description: Indicates that the Timeline was successfully updated.
-            Indicates that the draft Timeline was successfully created. In the
-            event the user already has a draft Timeline, the existing draft
-            Timeline is cleared and returned.
         '405':
           content:
             application/json:
@@ -287,12 +306,15 @@ paths:
                 type: object
                 properties:
                   body:
+                    description: The error message
+                    example: update timeline error
                     type: string
                   statusCode:
+                    example: 405
                     type: number
           description: >-
             Indicates that the user does not have the required access to create
-            a draft Timeline.
+            a Timeline.
       summary: Update a Timeline
       tags:
         - Security Timeline API
@@ -310,14 +332,20 @@ paths:
                   $ref: '#/components/schemas/TimelineStatus'
                   nullable: true
                 templateTimelineId:
+                  description: A unique identifier for the Timeline template.
+                  example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
                   nullable: true
                   type: string
                 templateTimelineVersion:
+                  description: Timeline template version number.
+                  example: 12
                   nullable: true
                   type: number
                 timeline:
                   $ref: '#/components/schemas/SavedTimeline'
                 timelineId:
+                  description: A unique identifier for the Timeline.
+                  example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
                   nullable: true
                   type: string
                 timelineType:
@@ -346,8 +374,11 @@ paths:
                 type: object
                 properties:
                   body:
+                    description: The error message
+                    example: update timeline error
                     type: string
                   statusCode:
+                    example: 405
                     type: number
           description: Indicates that there was an error in the Timeline creation.
       summary: Create a Timeline or Timeline template
@@ -611,6 +642,7 @@ paths:
               properties:
                 file: {}
                 isImmutable:
+                  description: Whether the Timeline should be immutable
                   enum:
                     - 'true'
                     - 'false'
@@ -633,10 +665,11 @@ paths:
                 type: object
                 properties:
                   body:
-                    type: string
+                    description: The error message
-                  id:
+                    example: Invalid file extension
                     type: string
                   statusCode:
+                    example: 400
                     type: number
           description: >-
             Indicates the import of Timelines was unsuccessful because of an
@@ -647,9 +680,12 @@ paths:
               schema:
                 type: object
                 properties:
-                  id:
+                  body:
+                    description: The error message
+                    example: Unable to find saved object client
                     type: string
                   statusCode:
+                    example: 404
                     type: number
           description: >-
             Indicates that we were unable to locate the saved object client
@@ -661,10 +697,11 @@ paths:
                 type: object
                 properties:
                   body:
-                    type: string
+                    description: The error message
-                  id:
+                    example: Could not import timelines
                     type: string
                   statusCode:
+                    example: 409
                     type: number
           description: Indicates the import of Timelines was unsuccessful.
       summary: Import Timelines
@@ -780,24 +817,28 @@ paths:
           name: sort_field
           schema:
             $ref: '#/components/schemas/SortFieldTimeline'
-        - in: query
+        - description: Whether to sort the results `ascending` or `descending`
+          in: query
           name: sort_order
           schema:
             enum:
               - asc
               - desc
             type: string
-        - in: query
+        - description: How many results should returned at once
+          in: query
           name: page_size
           schema:
             nullable: true
             type: string
-        - in: query
+        - description: How many pages should be skipped
+          in: query
           name: page_index
           schema:
             nullable: true
             type: string
-        - in: query
+        - description: Allows to search for timelines by their title
+          in: query
           name: search
           schema:
             nullable: true
@@ -815,20 +856,32 @@ paths:
                 type: object
                 properties:
                   customTemplateTimelineCount:
+                    description: The amount of custom Timeline templates in the results
+                    example: 2
                     type: number
                   defaultTimelineCount:
+                    description: The amount of `default` type Timelines in the results
+                    example: 90
                     type: number
                   elasticTemplateTimelineCount:
+                    description: The amount of Elastic's Timeline templates in the results
+                    example: 8
                     type: number
                   favoriteCount:
+                    description: The amount of favorited Timelines
+                    example: 5
                     type: number
                   templateTimelineCount:
+                    description: The amount of Timeline templates in the results
+                    example: 10
                     type: number
                   timeline:
                     items:
                       $ref: '#/components/schemas/TimelineResponse'
                     type: array
                   totalCount:
+                    description: The total amount of results
+                    example: 100
                     type: number
                 required:
                   - timeline
@@ -841,8 +894,11 @@ paths:
                 type: object
                 properties:
                   body:
+                    description: The error message
+                    example: get timeline error
                     type: string
                   statusCode:
+                    example: 405
                     type: number
           description: Bad request. The user supplied invalid data.
       summary: Get Timelines or Timeline templates
@@ -861,52 +917,46 @@ components:
         - orphan
       type: string
     BareNote:
-      type: object
+      allOf:
-      properties:
+        - $ref: '#/components/schemas/NoteCreatedAndUpdatedMetadata'
-        created:
+        - type: object
-          nullable: true
+          properties:
-          type: number
+            eventId:
-        createdBy:
+              description: The `_id` of the associated event for this note.
-          nullable: true
+              example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
-          type: string
+              nullable: true
-        eventId:
+              type: string
-          nullable: true
+            note:
-          type: string
+              description: The text of the note
-        note:
+              example: This is an example text
-          nullable: true
+              nullable: true
-          type: string
+              type: string
-        timelineId:
+            timelineId:
-          type: string
+              description: >-
-        updated:
+                The `savedObjectId` of the Timeline that this note is associated
-          nullable: true
+                with
-          type: number
+              example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
-        updatedBy:
+              type: string
-          nullable: true
+          required:
-          type: string
+            - timelineId
-      required:
-        - timelineId
     BarePinnedEvent:
-      type: object
+      allOf:
-      properties:
+        - $ref: '#/components/schemas/PinnedEventCreatedAndUpdatedMetadata'
-        created:
+        - type: object
-          nullable: true
+          properties:
-          type: number
+            eventId:
-        createdBy:
+              description: The `_id` of the associated event for this pinned event.
-          nullable: true
+              example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
-          type: string
+              type: string
-        eventId:
+            timelineId:
-          type: string
+              description: >-
-        timelineId:
+                The `savedObjectId` of the timeline that this pinned event is
-          type: string
+                associated with
-        updated:
+              example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
-          nullable: true
+              type: string
-          type: number
+          required:
-        updatedBy:
+            - eventId
-          nullable: true
+            - timelineId
-          type: string
-      required:
-        - eventId
-        - timelineId
     ColumnHeaderResult:
       type: object
       properties:
@@ -999,9 +1049,7 @@ components:
           $ref: '#/components/schemas/DataProviderType'
           nullable: true
     DataProviderType:
-      description: >-
+      description: The type of data provider.
-        The type of data provider to create. Valid values are `default` and
-        `template`.
       enum:
         - default
         - template
@@ -1035,6 +1083,10 @@ components:
         - savedObjectId
         - version
     FavoriteTimelineResult:
+      description: Indicates when and who marked a Timeline as a favorite.
+      example:
+        favoriteDate: 1741337636741
+        userName: elastic
       type: object
       properties:
         favoriteDate:
@@ -1047,6 +1099,16 @@ components:
           nullable: true
           type: string
     FilterTimelineResult:
+      example:
+        meta:
+          alias: Custom filter name
+          disabled: false
+          index: .alerts-security.alerts-default,logs-*
+          key: '@timestamp'
+          negate: false,
+          type: exists
+          value: exists
+        query: '{"exists":{"field":"@timestamp"}}'
       type: object
       properties:
         exists:
@@ -1120,26 +1182,43 @@ components:
       type: object
       properties:
         errors:
+          description: The list of failed Timeline imports
           items:
             type: object
             properties:
               error:
+                description: >-
+                  The error containing the reason why the timeline could not be
+                  imported
                 type: object
                 properties:
                   message:
+                    description: The reason why the timeline could not be imported
+                    example: Malformed JSON
                     type: string
                   status_code:
+                    description: The HTTP status code of the error
+                    example: 400
                     type: number
               id:
+                description: The ID of the timeline that failed to import
+                example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
                 type: string
           type: array
         success:
+          description: Indicates whether any of the Timelines were successfully imports
           type: boolean
         success_count:
+          description: The amount of successfully imported/updated Timelines
+          example: 99
           type: number
         timelines_installed:
+          description: The amount of successfully installed Timelines
+          example: 80
           type: number
         timelines_updated:
+          description: The amount of successfully updated Timelines
+          example: 19
           type: number
     ImportTimelines:
       allOf:
@@ -1179,18 +1258,46 @@ components:
         - type: object
           properties:
             noteId:
+              description: The `savedObjectId` of the note
+              example: 709f99c6-89b6-4953-9160-35945c8e174e
               type: string
             version:
+              description: The version of the note
+              example: WzQ2LDFd
               type: string
           required:
             - noteId
             - version
+    NoteCreatedAndUpdatedMetadata:
+      type: object
+      properties:
+        created:
+          description: The time the note was created, using a 13-digit Epoch timestamp.
+          example: 1587468588922
+          nullable: true
+          type: number
+        createdBy:
+          description: The user who created the note.
+          example: casetester
+          nullable: true
+          type: string
+        updated:
+          description: The last time the note was updated, using a 13-digit Epoch timestamp
+          example: 1741344876825
+          nullable: true
+          type: number
+        updatedBy:
+          description: The user who last updated the note
+          example: casetester
+          nullable: true
+          type: string
     PersistPinnedEventResponse:
       oneOf:
         - $ref: '#/components/schemas/PinnedEvent'
         - type: object
           properties:
             unpinned:
+              description: Indicates whether the event was successfully unpinned
               type: boolean
           required:
             - unpinned
@@ -1202,12 +1309,43 @@ components:
         - type: object
           properties:
             pinnedEventId:
+              description: The `savedObjectId` of this pinned event
+              example: 10r1929b-0af7-42bd-85a8-56e234f98h2f3
               type: string
             version:
+              description: The version of this pinned event
+              example: WzQ2LDFe
               type: string
           required:
             - pinnedEventId
             - version
+    PinnedEventCreatedAndUpdatedMetadata:
+      type: object
+      properties:
+        created:
+          description: >-
+            The time the pinned event was created, using a 13-digit Epoch
+            timestamp.
+          example: 1587468588922
+          nullable: true
+          type: number
+        createdBy:
+          description: The user who created the pinned event.
+          example: casetester
+          nullable: true
+          type: string
+        updated:
+          description: >-
+            The last time the pinned event was updated, using a 13-digit Epoch
+            timestamp
+          example: 1741344876825
+          nullable: true
+          type: number
+        updatedBy:
+          description: The user who last updated the pinned event
+          example: casetester
+          nullable: true
+          type: string
     QueryMatchResult:
       type: object
       properties:
@@ -1253,6 +1391,7 @@ components:
       required:
         - note
     RowRendererId:
+      description: Identifies the available row renderers
       enum:
         - alert
         - alerts
@@ -1294,25 +1433,53 @@ components:
       type: object
       properties:
         columns:
+          description: The Timeline's columns
+          example:
+            - columnHeaderType: not-filtered
+              id: '@timestamp'
+            - columnHeaderType: not-filtered
+              id: event.category
           items:
             $ref: '#/components/schemas/ColumnHeaderResult'
           nullable: true
           type: array
         created:
+          description: The time the Timeline was created, using a 13-digit Epoch timestamp.
+          example: 1587468588922
           nullable: true
           type: number
         createdBy:
+          description: The user who created the Timeline.
+          example: casetester
           nullable: true
           type: string
         dataProviders:
+          description: Object containing query clauses
+          example:
+            - enabled: true
+              excluded: false
+              id: >-
+                id-d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b
+              name: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b
+              queryMatch:
+                field: _id,
+                operator: ':'
+                value: >-
+                  d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b,
           items:
             $ref: '#/components/schemas/DataProviderResult'
           nullable: true
           type: array
         dataViewId:
+          description: ID of the Timeline's Data View
+          example: security-solution-default
           nullable: true
           type: string
         dateRange:
+          description: The Timeline's search period.
+          example:
+            end: 1587456479201
+            start: 1587370079200
           nullable: true
           type: object
           properties:
@@ -1329,9 +1496,17 @@ components:
                 - nullable: true
                   type: number
         description:
+          description: The Timeline's description
+          example: Investigating exposure of CVE XYZ
           nullable: true
           type: string
         eqlOptions:
+          description: EQL query that is used in the correlation tab
+          example:
+            eventCategoryField: event.category
+            query: sequence\n[process where process.name == "sudo"]\n[any where true]
+            size: 100
+            timestampField: '@timestamp'
           nullable: true
           type: object
           properties:
@@ -1354,9 +1529,15 @@ components:
               nullable: true
               type: string
         eventType:
+          deprecated: true
+          description: Event types displayed in the Timeline
+          example: all
           nullable: true
           type: string
         excludedRowRendererIds:
+          description: >-
+            A list of row renderers that should not be used when in `Event
+            renderers` mode
           items:
             $ref: '#/components/schemas/RowRendererId'
           nullable: true
@@ -1367,53 +1548,81 @@ components:
           nullable: true
           type: array
         filters:
+          description: A list of filters that should be applied to the query
           items:
             $ref: '#/components/schemas/FilterTimelineResult'
           nullable: true
           type: array
         indexNames:
+          description: >-
+            A list of index names to use in the query (e.g. when the default
+            data view has been modified)
+          example:
+            - .logs*
           items:
             type: string
           nullable: true
           type: array
         kqlMode:
+          description: >-
+            Indicates whether the KQL bar filters the query results or searches
+            for additional results, where:
+              * `filter`: filters query results
+              * `search`: displays additional search results
+          example: search
           nullable: true
           type: string
         kqlQuery:
           $ref: '#/components/schemas/SerializedFilterQueryResult'
           nullable: true
         savedQueryId:
+          description: The ID of the saved query that might be used in the Query tab
+          example: c7b16904-02d7-4f32-b8f2-cc20f9625d6e
           nullable: true
           type: string
         savedSearchId:
+          description: The ID of the saved search that is used in the ES|QL tab
+          example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
           nullable: true
           type: string
         sort:
           $ref: '#/components/schemas/Sort'
           nullable: true
         status:
-          enum:
+          $ref: '#/components/schemas/TimelineStatus'
-            - active
-            - draft
-            - immutable
           nullable: true
-          type: string
         templateTimelineId:
+          description: >-
+            A unique ID (UUID) for Timeline templates. For Timelines, the value
+            is `null`.
+          example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
           nullable: true
           type: string
         templateTimelineVersion:
+          description: >-
+            Timeline template version number. For Timelines, the value is
+            `null`.
+          example: 12
           nullable: true
           type: number
         timelineType:
           $ref: '#/components/schemas/TimelineType'
           nullable: true
         title:
+          description: The Timeline's title.
+          example: CVE XYZ investigation
           nullable: true
           type: string
         updated:
+          description: >-
+            The last time the Timeline was updated, using a 13-digit Epoch
+            timestamp
+          example: 1741344876825
           nullable: true
           type: number
         updatedBy:
+          description: The user who last updated the Timeline
+          example: casetester
           nullable: true
           type: string
     SavedTimelineWithSavedObjectId:
@@ -1422,13 +1631,25 @@ components:
         - type: object
           properties:
             savedObjectId:
+              description: The `savedObjectId` of the Timeline or Timeline template
+              example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
               type: string
             version:
+              description: The version of the Timeline or Timeline template
+              example: WzE0LDFd
               type: string
           required:
             - savedObjectId
             - version
     SerializedFilterQueryResult:
+      description: KQL bar query.
+      example:
+        filterQuery: null
+        kuery:
+          expression: '_id : *'
+          kind: kuery
+        serializedQuery: >-
+          {"bool":{"should":[{"exists":{"field":"_id"}}],"minimum_should_match":1}}
       type: object
       properties:
         filterQuery:
@@ -1463,6 +1684,10 @@ components:
         - created
       type: string
     SortObject:
+      description: Object indicating how rows are sorted in the Timeline's grid
+      example:
+        columnId: '@timestamp'
+        sortDirection: desc
       type: object
       properties:
         columnId:
@@ -1481,26 +1706,41 @@ components:
         - type: object
           properties:
             eventIdToNoteIds:
+              description: A list of all the notes that are associated to this Timeline.
               items:
                 $ref: '#/components/schemas/Note'
               nullable: true
               type: array
             noteIds:
+              description: >-
+                A list of all the ids of notes that are associated to this
+                Timeline.
+              example:
+                - 709f99c6-89b6-4953-9160-35945c8e174e
               items:
                 type: string
               nullable: true
               type: array
             notes:
+              description: A list of all the notes that are associated to this Timeline.
               items:
                 $ref: '#/components/schemas/Note'
               nullable: true
               type: array
             pinnedEventIds:
+              description: >-
+                A list of all the ids of pinned events that are associated to
+                this Timeline.
+              example:
+                - 983f99c6-89b6-4953-9160-35945c8a194f
               items:
                 type: string
               nullable: true
               type: array
             pinnedEventsSaveObject:
+              description: >-
+                A list of all the pinned events that are associated to this
+                Timeline.
               items:
                 $ref: '#/components/schemas/PinnedEvent'
               nullable: true
@@ -1543,18 +1783,14 @@ components:
             - savedObjectId
             - version
     TimelineStatus:
-      description: >-
+      description: The status of the Timeline.
-        The status of the timeline. Valid values are `active`, `draft`, and
-        `immutable`.
       enum:
         - active
         - draft
         - immutable
       type: string
     TimelineType:
-      description: >-
+      description: The type of Timeline.
-        The type of timeline to create. Valid values are `default` and
-        `template`.
       enum:
         - default
         - template

x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_timeline_api_2023_10_31.bundled.schema.yaml

@@ -119,24 +119,17 @@ paths:
             schema:
               type: object
               properties:
-                eventDataView:
-                  nullable: true
-                  type: string
-                eventIngested:
-                  nullable: true
-                  type: string
-                eventTimestamp:
-                  nullable: true
-                  type: string
                 note:
                   $ref: '#/components/schemas/BareNote'
+                  description: The note to add or update.
                 noteId:
+                  description: The `savedObjectId` of the note
+                  example: 709f99c6-89b6-4953-9160-35945c8e174e
                   nullable: true
                   type: string
-                overrideOwner:
-                  nullable: true
-                  type: boolean
                 version:
+                  description: The version of the note
+                  example: WzQ2LDFd
                   nullable: true
                   type: string
               required:
@@ -156,7 +149,7 @@ paths:
         - access:securitySolution
   /api/pinned_event:
     patch:
-      description: Pin an event to an existing Timeline.
+      description: Pin/unpin an event to/from an existing Timeline.
       operationId: PersistPinnedEventRoute
       requestBody:
         content:
@@ -165,16 +158,24 @@ paths:
               type: object
               properties:
                 eventId:
+                  description: The `_id` of the associated event for this pinned event.
+                  example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
                   type: string
                 pinnedEventId:
+                  description: The `savedObjectId` of the pinned event you want to unpin.
+                  example: 10r1929b-0af7-42bd-85a8-56e234f98h2f3
                   nullable: true
                   type: string
                 timelineId:
+                  description: >-
+                    The `savedObjectId` of the timeline that you want this
+                    pinned event unpinned from.
+                  example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
                   type: string
               required:
                 - eventId
                 - timelineId
-        description: The pinned event to add or update, along with additional metadata.
+        description: The pinned event to add or unpin, along with additional metadata.
         required: true
       responses:
         '200':
@@ -182,8 +183,10 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/PersistPinnedEventResponse'
-          description: Indicates the event was successfully pinned to the Timeline.
+          description: >-
-      summary: Pin an event
+            Indicates the event was successfully pinned to or unpinned from the
+            Timeline.
+      summary: Pin/unpin an event
       tags:
         - Security Timeline API
         - access:securitySolution
@@ -198,13 +201,21 @@ paths:
               type: object
               properties:
                 savedObjectIds:
+                  description: >-
+                    The list of IDs of the Timelines or Timeline templates to
+                    delete
+                  example:
+                    - 15c1929b-0af7-42bd-85a8-56e234cc7c4e
                   items:
                     type: string
                   type: array
                 searchIds:
                   description: >-
-                    Saved search ids that should be deleted alongside the
+                    Saved search IDs that should be deleted alongside the
                     timelines
+                  example:
+                    - 23f3-43g34g322-e5g5hrh6h-45454
+                    - 6ce1b592-84e3-4b4a-9552-f189d4b82075
                   items:
                     type: string
                   type: array
@@ -223,12 +234,12 @@ paths:
       description: Get the details of an existing saved Timeline or Timeline template.
       operationId: GetTimeline
       parameters:
-        - description: The ID of the template timeline to retrieve
+        - description: The `savedObjectId` of the template timeline to retrieve
           in: query
           name: template_timeline_id
           schema:
             type: string
-        - description: The ID of the Timeline to retrieve.
+        - description: The `savedObjectId` of the Timeline to retrieve.
           in: query
           name: id
           schema:
@@ -258,10 +269,21 @@ paths:
               properties:
                 timeline:
                   $ref: '#/components/schemas/SavedTimeline'
+                  description: >-
+                    The timeline object of the Timeline or Timeline template
+                    that you’re updating.
                 timelineId:
+                  description: >-
+                    The `savedObjectId` of the Timeline or Timeline template
+                    that you’re updating.
+                  example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
                   nullable: true
                   type: string
                 version:
+                  description: >-
+                    The version of the Timeline or Timeline template that you’re
+                    updating.
+                  example: WzE0LDFd
                   nullable: true
                   type: string
               required:
@@ -276,10 +298,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/PersistTimelineResponse'
-          description: >-
+          description: Indicates that the Timeline was successfully updated.
-            Indicates that the draft Timeline was successfully created. In the
-            event the user already has a draft Timeline, the existing draft
-            Timeline is cleared and returned.
         '405':
           content:
             application/json:
@@ -287,12 +306,15 @@ paths:
                 type: object
                 properties:
                   body:
+                    description: The error message
+                    example: update timeline error
                     type: string
                   statusCode:
+                    example: 405
                     type: number
           description: >-
             Indicates that the user does not have the required access to create
-            a draft Timeline.
+            a Timeline.
       summary: Update a Timeline
       tags:
         - Security Timeline API
@@ -310,14 +332,20 @@ paths:
                   $ref: '#/components/schemas/TimelineStatus'
                   nullable: true
                 templateTimelineId:
+                  description: A unique identifier for the Timeline template.
+                  example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
                   nullable: true
                   type: string
                 templateTimelineVersion:
+                  description: Timeline template version number.
+                  example: 12
                   nullable: true
                   type: number
                 timeline:
                   $ref: '#/components/schemas/SavedTimeline'
                 timelineId:
+                  description: A unique identifier for the Timeline.
+                  example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
                   nullable: true
                   type: string
                 timelineType:
@@ -346,8 +374,11 @@ paths:
                 type: object
                 properties:
                   body:
+                    description: The error message
+                    example: update timeline error
                     type: string
                   statusCode:
+                    example: 405
                     type: number
           description: Indicates that there was an error in the Timeline creation.
       summary: Create a Timeline or Timeline template
@@ -611,6 +642,7 @@ paths:
               properties:
                 file: {}
                 isImmutable:
+                  description: Whether the Timeline should be immutable
                   enum:
                     - 'true'
                     - 'false'
@@ -633,10 +665,11 @@ paths:
                 type: object
                 properties:
                   body:
-                    type: string
+                    description: The error message
-                  id:
+                    example: Invalid file extension
                     type: string
                   statusCode:
+                    example: 400
                     type: number
           description: >-
             Indicates the import of Timelines was unsuccessful because of an
@@ -647,9 +680,12 @@ paths:
               schema:
                 type: object
                 properties:
-                  id:
+                  body:
+                    description: The error message
+                    example: Unable to find saved object client
                     type: string
                   statusCode:
+                    example: 404
                     type: number
           description: >-
             Indicates that we were unable to locate the saved object client
@@ -661,10 +697,11 @@ paths:
                 type: object
                 properties:
                   body:
-                    type: string
+                    description: The error message
-                  id:
+                    example: Could not import timelines
                     type: string
                   statusCode:
+                    example: 409
                     type: number
           description: Indicates the import of Timelines was unsuccessful.
       summary: Import Timelines
@@ -780,24 +817,28 @@ paths:
           name: sort_field
           schema:
             $ref: '#/components/schemas/SortFieldTimeline'
-        - in: query
+        - description: Whether to sort the results `ascending` or `descending`
+          in: query
           name: sort_order
           schema:
             enum:
               - asc
               - desc
             type: string
-        - in: query
+        - description: How many results should returned at once
+          in: query
           name: page_size
           schema:
             nullable: true
             type: string
-        - in: query
+        - description: How many pages should be skipped
+          in: query
           name: page_index
           schema:
             nullable: true
             type: string
-        - in: query
+        - description: Allows to search for timelines by their title
+          in: query
           name: search
           schema:
             nullable: true
@@ -815,20 +856,32 @@ paths:
                 type: object
                 properties:
                   customTemplateTimelineCount:
+                    description: The amount of custom Timeline templates in the results
+                    example: 2
                     type: number
                   defaultTimelineCount:
+                    description: The amount of `default` type Timelines in the results
+                    example: 90
                     type: number
                   elasticTemplateTimelineCount:
+                    description: The amount of Elastic's Timeline templates in the results
+                    example: 8
                     type: number
                   favoriteCount:
+                    description: The amount of favorited Timelines
+                    example: 5
                     type: number
                   templateTimelineCount:
+                    description: The amount of Timeline templates in the results
+                    example: 10
                     type: number
                   timeline:
                     items:
                       $ref: '#/components/schemas/TimelineResponse'
                     type: array
                   totalCount:
+                    description: The total amount of results
+                    example: 100
                     type: number
                 required:
                   - timeline
@@ -841,8 +894,11 @@ paths:
                 type: object
                 properties:
                   body:
+                    description: The error message
+                    example: get timeline error
                     type: string
                   statusCode:
+                    example: 405
                     type: number
           description: Bad request. The user supplied invalid data.
       summary: Get Timelines or Timeline templates
@@ -861,52 +917,46 @@ components:
         - orphan
       type: string
     BareNote:
-      type: object
+      allOf:
-      properties:
+        - $ref: '#/components/schemas/NoteCreatedAndUpdatedMetadata'
-        created:
+        - type: object
-          nullable: true
+          properties:
-          type: number
+            eventId:
-        createdBy:
+              description: The `_id` of the associated event for this note.
-          nullable: true
+              example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
-          type: string
+              nullable: true
-        eventId:
+              type: string
-          nullable: true
+            note:
-          type: string
+              description: The text of the note
-        note:
+              example: This is an example text
-          nullable: true
+              nullable: true
-          type: string
+              type: string
-        timelineId:
+            timelineId:
-          type: string
+              description: >-
-        updated:
+                The `savedObjectId` of the Timeline that this note is associated
-          nullable: true
+                with
-          type: number
+              example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
-        updatedBy:
+              type: string
-          nullable: true
+          required:
-          type: string
+            - timelineId
-      required:
-        - timelineId
     BarePinnedEvent:
-      type: object
+      allOf:
-      properties:
+        - $ref: '#/components/schemas/PinnedEventCreatedAndUpdatedMetadata'
-        created:
+        - type: object
-          nullable: true
+          properties:
-          type: number
+            eventId:
-        createdBy:
+              description: The `_id` of the associated event for this pinned event.
-          nullable: true
+              example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
-          type: string
+              type: string
-        eventId:
+            timelineId:
-          type: string
+              description: >-
-        timelineId:
+                The `savedObjectId` of the timeline that this pinned event is
-          type: string
+                associated with
-        updated:
+              example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
-          nullable: true
+              type: string
-          type: number
+          required:
-        updatedBy:
+            - eventId
-          nullable: true
+            - timelineId
-          type: string
-      required:
-        - eventId
-        - timelineId
     ColumnHeaderResult:
       type: object
       properties:
@@ -999,9 +1049,7 @@ components:
           $ref: '#/components/schemas/DataProviderType'
           nullable: true
     DataProviderType:
-      description: >-
+      description: The type of data provider.
-        The type of data provider to create. Valid values are `default` and
-        `template`.
       enum:
         - default
         - template
@@ -1035,6 +1083,10 @@ components:
         - savedObjectId
         - version
     FavoriteTimelineResult:
+      description: Indicates when and who marked a Timeline as a favorite.
+      example:
+        favoriteDate: 1741337636741
+        userName: elastic
       type: object
       properties:
         favoriteDate:
@@ -1047,6 +1099,16 @@ components:
           nullable: true
           type: string
     FilterTimelineResult:
+      example:
+        meta:
+          alias: Custom filter name
+          disabled: false
+          index: .alerts-security.alerts-default,logs-*
+          key: '@timestamp'
+          negate: false,
+          type: exists
+          value: exists
+        query: '{"exists":{"field":"@timestamp"}}'
       type: object
       properties:
         exists:
@@ -1120,26 +1182,43 @@ components:
       type: object
       properties:
         errors:
+          description: The list of failed Timeline imports
           items:
             type: object
             properties:
               error:
+                description: >-
+                  The error containing the reason why the timeline could not be
+                  imported
                 type: object
                 properties:
                   message:
+                    description: The reason why the timeline could not be imported
+                    example: Malformed JSON
                     type: string
                   status_code:
+                    description: The HTTP status code of the error
+                    example: 400
                     type: number
               id:
+                description: The ID of the timeline that failed to import
+                example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
                 type: string
           type: array
         success:
+          description: Indicates whether any of the Timelines were successfully imports
           type: boolean
         success_count:
+          description: The amount of successfully imported/updated Timelines
+          example: 99
           type: number
         timelines_installed:
+          description: The amount of successfully installed Timelines
+          example: 80
           type: number
         timelines_updated:
+          description: The amount of successfully updated Timelines
+          example: 19
           type: number
     ImportTimelines:
       allOf:
@@ -1179,18 +1258,46 @@ components:
         - type: object
           properties:
             noteId:
+              description: The `savedObjectId` of the note
+              example: 709f99c6-89b6-4953-9160-35945c8e174e
               type: string
             version:
+              description: The version of the note
+              example: WzQ2LDFd
               type: string
           required:
             - noteId
             - version
+    NoteCreatedAndUpdatedMetadata:
+      type: object
+      properties:
+        created:
+          description: The time the note was created, using a 13-digit Epoch timestamp.
+          example: 1587468588922
+          nullable: true
+          type: number
+        createdBy:
+          description: The user who created the note.
+          example: casetester
+          nullable: true
+          type: string
+        updated:
+          description: The last time the note was updated, using a 13-digit Epoch timestamp
+          example: 1741344876825
+          nullable: true
+          type: number
+        updatedBy:
+          description: The user who last updated the note
+          example: casetester
+          nullable: true
+          type: string
     PersistPinnedEventResponse:
       oneOf:
         - $ref: '#/components/schemas/PinnedEvent'
         - type: object
           properties:
             unpinned:
+              description: Indicates whether the event was successfully unpinned
               type: boolean
           required:
             - unpinned
@@ -1202,12 +1309,43 @@ components:
         - type: object
           properties:
             pinnedEventId:
+              description: The `savedObjectId` of this pinned event
+              example: 10r1929b-0af7-42bd-85a8-56e234f98h2f3
               type: string
             version:
+              description: The version of this pinned event
+              example: WzQ2LDFe
               type: string
           required:
             - pinnedEventId
             - version
+    PinnedEventCreatedAndUpdatedMetadata:
+      type: object
+      properties:
+        created:
+          description: >-
+            The time the pinned event was created, using a 13-digit Epoch
+            timestamp.
+          example: 1587468588922
+          nullable: true
+          type: number
+        createdBy:
+          description: The user who created the pinned event.
+          example: casetester
+          nullable: true
+          type: string
+        updated:
+          description: >-
+            The last time the pinned event was updated, using a 13-digit Epoch
+            timestamp
+          example: 1741344876825
+          nullable: true
+          type: number
+        updatedBy:
+          description: The user who last updated the pinned event
+          example: casetester
+          nullable: true
+          type: string
     QueryMatchResult:
       type: object
       properties:
@@ -1253,6 +1391,7 @@ components:
       required:
         - note
     RowRendererId:
+      description: Identifies the available row renderers
       enum:
         - alert
         - alerts
@@ -1294,25 +1433,53 @@ components:
       type: object
       properties:
         columns:
+          description: The Timeline's columns
+          example:
+            - columnHeaderType: not-filtered
+              id: '@timestamp'
+            - columnHeaderType: not-filtered
+              id: event.category
           items:
             $ref: '#/components/schemas/ColumnHeaderResult'
           nullable: true
           type: array
         created:
+          description: The time the Timeline was created, using a 13-digit Epoch timestamp.
+          example: 1587468588922
           nullable: true
           type: number
         createdBy:
+          description: The user who created the Timeline.
+          example: casetester
           nullable: true
           type: string
         dataProviders:
+          description: Object containing query clauses
+          example:
+            - enabled: true
+              excluded: false
+              id: >-
+                id-d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b
+              name: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b
+              queryMatch:
+                field: _id,
+                operator: ':'
+                value: >-
+                  d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b,
           items:
             $ref: '#/components/schemas/DataProviderResult'
           nullable: true
           type: array
         dataViewId:
+          description: ID of the Timeline's Data View
+          example: security-solution-default
           nullable: true
           type: string
         dateRange:
+          description: The Timeline's search period.
+          example:
+            end: 1587456479201
+            start: 1587370079200
           nullable: true
           type: object
           properties:
@@ -1329,9 +1496,17 @@ components:
                 - nullable: true
                   type: number
         description:
+          description: The Timeline's description
+          example: Investigating exposure of CVE XYZ
           nullable: true
           type: string
         eqlOptions:
+          description: EQL query that is used in the correlation tab
+          example:
+            eventCategoryField: event.category
+            query: sequence\n[process where process.name == "sudo"]\n[any where true]
+            size: 100
+            timestampField: '@timestamp'
           nullable: true
           type: object
           properties:
@@ -1354,9 +1529,15 @@ components:
               nullable: true
               type: string
         eventType:
+          deprecated: true
+          description: Event types displayed in the Timeline
+          example: all
           nullable: true
           type: string
         excludedRowRendererIds:
+          description: >-
+            A list of row renderers that should not be used when in `Event
+            renderers` mode
           items:
             $ref: '#/components/schemas/RowRendererId'
           nullable: true
@@ -1367,53 +1548,81 @@ components:
           nullable: true
           type: array
         filters:
+          description: A list of filters that should be applied to the query
           items:
             $ref: '#/components/schemas/FilterTimelineResult'
           nullable: true
           type: array
         indexNames:
+          description: >-
+            A list of index names to use in the query (e.g. when the default
+            data view has been modified)
+          example:
+            - .logs*
           items:
             type: string
           nullable: true
           type: array
         kqlMode:
+          description: >-
+            Indicates whether the KQL bar filters the query results or searches
+            for additional results, where:
+              * `filter`: filters query results
+              * `search`: displays additional search results
+          example: search
           nullable: true
           type: string
         kqlQuery:
           $ref: '#/components/schemas/SerializedFilterQueryResult'
           nullable: true
         savedQueryId:
+          description: The ID of the saved query that might be used in the Query tab
+          example: c7b16904-02d7-4f32-b8f2-cc20f9625d6e
           nullable: true
           type: string
         savedSearchId:
+          description: The ID of the saved search that is used in the ES|QL tab
+          example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
           nullable: true
           type: string
         sort:
           $ref: '#/components/schemas/Sort'
           nullable: true
         status:
-          enum:
+          $ref: '#/components/schemas/TimelineStatus'
-            - active
-            - draft
-            - immutable
           nullable: true
-          type: string
         templateTimelineId:
+          description: >-
+            A unique ID (UUID) for Timeline templates. For Timelines, the value
+            is `null`.
+          example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
           nullable: true
           type: string
         templateTimelineVersion:
+          description: >-
+            Timeline template version number. For Timelines, the value is
+            `null`.
+          example: 12
           nullable: true
           type: number
         timelineType:
           $ref: '#/components/schemas/TimelineType'
           nullable: true
         title:
+          description: The Timeline's title.
+          example: CVE XYZ investigation
           nullable: true
           type: string
         updated:
+          description: >-
+            The last time the Timeline was updated, using a 13-digit Epoch
+            timestamp
+          example: 1741344876825
           nullable: true
           type: number
         updatedBy:
+          description: The user who last updated the Timeline
+          example: casetester
           nullable: true
           type: string
     SavedTimelineWithSavedObjectId:
@@ -1422,13 +1631,25 @@ components:
         - type: object
           properties:
             savedObjectId:
+              description: The `savedObjectId` of the Timeline or Timeline template
+              example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
               type: string
             version:
+              description: The version of the Timeline or Timeline template
+              example: WzE0LDFd
               type: string
           required:
             - savedObjectId
             - version
     SerializedFilterQueryResult:
+      description: KQL bar query.
+      example:
+        filterQuery: null
+        kuery:
+          expression: '_id : *'
+          kind: kuery
+        serializedQuery: >-
+          {"bool":{"should":[{"exists":{"field":"_id"}}],"minimum_should_match":1}}
       type: object
       properties:
         filterQuery:
@@ -1463,6 +1684,10 @@ components:
         - created
       type: string
     SortObject:
+      description: Object indicating how rows are sorted in the Timeline's grid
+      example:
+        columnId: '@timestamp'
+        sortDirection: desc
       type: object
       properties:
         columnId:
@@ -1481,26 +1706,41 @@ components:
         - type: object
           properties:
             eventIdToNoteIds:
+              description: A list of all the notes that are associated to this Timeline.
               items:
                 $ref: '#/components/schemas/Note'
               nullable: true
               type: array
             noteIds:
+              description: >-
+                A list of all the ids of notes that are associated to this
+                Timeline.
+              example:
+                - 709f99c6-89b6-4953-9160-35945c8e174e
               items:
                 type: string
               nullable: true
               type: array
             notes:
+              description: A list of all the notes that are associated to this Timeline.
               items:
                 $ref: '#/components/schemas/Note'
               nullable: true
               type: array
             pinnedEventIds:
+              description: >-
+                A list of all the ids of pinned events that are associated to
+                this Timeline.
+              example:
+                - 983f99c6-89b6-4953-9160-35945c8a194f
               items:
                 type: string
               nullable: true
               type: array
             pinnedEventsSaveObject:
+              description: >-
+                A list of all the pinned events that are associated to this
+                Timeline.
               items:
                 $ref: '#/components/schemas/PinnedEvent'
               nullable: true
@@ -1543,18 +1783,14 @@ components:
             - savedObjectId
             - version
     TimelineStatus:
-      description: >-
+      description: The status of the Timeline.
-        The status of the timeline. Valid values are `active`, `draft`, and
-        `immutable`.
       enum:
         - active
         - draft
         - immutable
       type: string
     TimelineType:
-      description: >-
+      description: The type of Timeline.
-        The type of timeline to create. Valid values are `default` and
-        `template`.
       enum:
         - default
         - template

x-pack/test/api_integration/services/security_solution_api.gen.ts

@@ -1300,7 +1300,7 @@ finalize it.
         .send(props.body as object);
     },
     /**
-     * Pin an event to an existing Timeline.
+     * Pin/unpin an event to/from an existing Timeline.
      */
     persistPinnedEventRoute(props: PersistPinnedEventRouteProps, kibanaSpace: string = 'default') {
       return supertest