Improves Timeline API docs content

x-pack/plugins/security_solution/common/api/timeline/clean_draft_timelines/clean_draft_timelines_route.schema.yaml

@@ -15,13 +15,15 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: CleanDraftTimelines
-      summary: Retrieves a draft timeline or timeline template.
+      summary: Create a clean draft Timeline or Timeline template
       description: |
-        Retrieves a clean draft timeline. If a draft timeline does not exist, it is created and returned.
+        Create a clean draft Timeline or Timeline template for the current user.
+        > info
+        > If the user already has a draft Timeline, the existing draft Timeline is cleared and returned.
       tags:
         - access:securitySolution
       requestBody:
-        description: The type of timeline to create. Valid values are `default` and `template`.
+        description: The type of Timeline to create. Valid values are `default` and `template`.
         required: true
         content:
           application/json:
@@ -33,7 +35,7 @@ paths:
                   $ref: '../model/components.schema.yaml#/components/schemas/TimelineType'
       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 draft Timeline was successfully created. In the event the user already has a draft Timeline, the existing draft Timeline is cleared and returned.
           content:
             application/json:
               schema:
@@ -51,7 +53,7 @@ paths:
                           timeline:
                             $ref: '../model/components.schema.yaml#/components/schemas/TimelineResponse'
         '403':
-          description: Indicates that the user does not have the required permissions to create a draft timeline.
+          description: Indicates that the user does not have the required permissions to create a draft Timeline.
           content:
             application:json:
               schema:
@@ -62,7 +64,7 @@ paths:
                   status_code:
                     type: number
         '409':
-          description: Indicates that there is already a draft timeline with the given timelineId.
+          description: Indicates that there is already a draft Timeline with the given `timelineId`.
           content:
             application:json:
               schema:

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

@@ -18,11 +18,12 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: CreateTimelines
-      summary: Creates a new timeline.
+      summary: Create a Timeline or Timeline template
+      description: Create a new Timeline or Timeline template.
       tags:
         - access:securitySolution
       requestBody:
-        description: The required timeline fields used to create a new timeline along with optional fields that will be created if not provided.
+        description: The required Timeline fields used to create a new Timeline, along with optional fields that will be created if not provided.
         required: true
         content:
           application/json:
@@ -53,7 +54,7 @@ paths:
                   $ref: '../model/components.schema.yaml#/components/schemas/SavedTimeline'
       responses:
         '200':
-          description: Indicates the timeline was successfully created.
+          description: Indicates the Timeline was successfully created.
           content:
             application/json:
               schema:
@@ -70,7 +71,7 @@ paths:
                           timeline:
                             $ref: '../model/components.schema.yaml#/components/schemas/TimelineResponse'
         '405':
-          description: Indicates that there was an error in the timeline creation.
+          description: Indicates that there was an error in the Timeline creation.
           content:
             application/json:
               schema:

x-pack/plugins/security_solution/common/api/timeline/delete_note/delete_note_route.schema.yaml

@@ -15,11 +15,12 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: DeleteNote
-      summary: Deletes a note from a timeline.
+      summary: Delete a note
+      description: Delete a note from a Timeline using the note ID.
       tags:
         - access:securitySolution
       requestBody:
-        description: The id of the note to delete.
+        description: The ID of the note to delete.
         required: true
         content:
           application/json:

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

@@ -18,11 +18,12 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: DeleteTimelines
-      summary: Deletes one or more timelines or timeline templates.
+      summary: Delete Timelines or Timeline templates
+      description: Delete one or more Timelines or Timeline templates.
       tags:
         - access:securitySolution
       requestBody:
-        description: The ids of the timelines or timeline templates to delete.
+        description: The IDs of the Timelines or Timeline templates to delete.
         required: true
         content:
           application/json:
@@ -41,7 +42,7 @@ paths:
                     type: string
       responses:
         '200':
-          description: Indicates the timeline was successfully deleted.
+          description: Indicates the Timeline was successfully deleted.
           content:
             application/json:
               schema:

x-pack/plugins/security_solution/common/api/timeline/export_timelines/export_timelines_route.schema.yaml

@@ -18,7 +18,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: ExportTimelines
-      summary: Exports timelines as an NDJSON file
+      summary: Export Timelines
+      description: Export Timelines as an NDJSON file.
       tags:
         - access:securitySolution
       parameters:
@@ -29,7 +30,7 @@ paths:
             type: string
           description: The name of the file to export
       requestBody:
-        description: The ids of the timelines to export
+        description: The IDs of the Timelines to export
         required: true
         content:
           application/json:
@@ -43,14 +44,14 @@ paths:
                     type: string
       responses:
         '200':
-          description: Indicates the timelines were successfully exported
+          description: Indicates the Timelines were successfully exported.
           content:
             application/ndjson:
               schema:
                 type: string
                 description: NDJSON of the exported timelines
         '400':
-          description: Indicates that the export size limit was exceeded
+          description: Indicates that the export size limit was exceeded.
           content:
             application/ndjson:
               schema:

x-pack/plugins/security_solution/common/api/timeline/get_draft_timelines/get_draft_timelines_route.schema.yaml

@@ -15,7 +15,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: GetDraftTimelines
-      summary: Retrieves the draft timeline for the current user. If the user does not have a draft timeline, an empty timeline is returned.
+      summary: Get draft Timeline or Timeline template details
+      description: Get the details of the draft Timeline  or Timeline template for the current user. If the user doesn't have a draft Timeline, an empty Timeline is returned.
       tags:
         - access:securitySolution
       parameters:
@@ -26,7 +27,7 @@ paths:
             $ref: '../model/components.schema.yaml#/components/schemas/TimelineType'
       responses:
         '200':
-          description: Indicates that the draft timeline was successfully retrieved.
+          description: Indicates that the draft Timeline was successfully retrieved.
           content:
             application/json:
               schema:
@@ -44,7 +45,7 @@ paths:
                           timeline:
                             $ref: '../model/components.schema.yaml#/components/schemas/TimelineResponse'
         '403':
-          description: If a draft timeline was not found and we attempted to create one, it indicates that the user does not have the required permissions to create a draft timeline.
+          description: If a draft Timeline was not found and we attempted to create one, it indicates that the user does not have the required permissions to create a draft Timeline.
           content:
             application:json:
               schema:
@@ -55,7 +56,7 @@ paths:
                   status_code:
                     type: number
         '409':
-          description: This should never happen, but if a draft timeline was not found and we attempted to create one, it indicates that there is already a draft timeline with the given timelineId.
+          description: This should never happen, but if a draft Timeline was not found and we attempted to create one, it indicates that there is already a draft Timeline with the given `timelineId`.
           content:
             application:json:
               schema:

x-pack/plugins/security_solution/common/api/timeline/get_notes/get_notes_route.schema.yaml

@@ -15,8 +15,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: GetNotes
-      description: Gets notes
-      summary: Get all notes for a given document.
+      description: Get all notes for a given document.
+      summary: Get notes
       tags:
         - access:securitySolution
       parameters:

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

@@ -18,7 +18,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: GetTimeline
-      summary: Get an existing saved timeline or timeline template. This API is used to retrieve an existing saved timeline or timeline template.
+      summary: Get Timeline or Timeline template details
+      description: Get the details of an existing saved Timeline or Timeline template.
       tags:
         - access:securitySolution
       parameters:
@@ -34,7 +35,7 @@ paths:
           description: The ID of the timeline to retrieve
       responses:
         '200':
-          description: Indicates that the (template) timeline was found and returned.
+          description: Indicates that the (template) Timeline was found and returned.
           content:
             application/json:
               schema:

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

@@ -18,7 +18,8 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: GetTimelines
-      summary: This API is used to retrieve a list of existing saved timelines or timeline templates.
+      summary: Get Timelines or Timeline templates
+      description: Get a list of all saved Timelines or Timeline templates.
       tags:
         - access:securitySolution
       parameters:
@@ -69,7 +70,7 @@ paths:
             nullable: true
       responses:
         '200':
-          description: Indicates that the (template) timelines were found and returned.
+          description: Indicates that the (template) Timelines were found and returned.
           content:
             application/json:
               schema:

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

@@ -18,11 +18,12 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: ImportTimelines
-      summary: Imports timelines.
+      summary: Import Timelines
+      descriptions: Import Timelines.
       tags:
         - access:securitySolution
       requestBody:
-        description: The timelines to import as a readable stream.
+        description: The Timelines to import as a readable stream.
         required: true
         content:
           application/json:
@@ -50,7 +51,7 @@ paths:
                                 - 'false'
       responses:
         '200':
-          description: Indicates the import of timelines was successful.
+          description: Indicates the import of Timelines was successful.
           content:
             application/json:
               schema:
@@ -61,7 +62,7 @@ paths:
                     $ref: '../model/components.schema.yaml#/components/schemas/ImportTimelineResult'
 
         '400':
-          description: Indicates the import of timelines was unsuccessful because of an invalid file extension.
+          description: Indicates the import of Timelines was unsuccessful because of an invalid file extension.
           content:
             application/json:
               schema:
@@ -86,7 +87,7 @@ paths:
                   statusCode:
                     type: number
         '409':
-          description: Indicates the import of timelines was unsuccessful.
+          description: Indicates the import of Timelines was unsuccessful.
           content:
             application/json:
               schema:

x-pack/plugins/security_solution/common/api/timeline/install_prepackaged_timelines/install_prepackaged_timelines_route.schema.yaml

@@ -15,11 +15,12 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: InstallPrepackedTimelines
-      summary: Installs prepackaged timelines.
+      summary: Install prepackaged Timelines
+      description: Install or update prepackaged Timelines.
       tags:
         - access:securitySolution
       requestBody:
-        description: The timelines to install or update.
+        description: The Timelines to install or update.
         required: true
         content:
           application/json:
@@ -43,7 +44,7 @@ paths:
                     $ref: '../model/components.schema.yaml#/components/schemas/SavedTimeline'
       responses:
         '200':
-          description: Indicates the installation of prepackaged timelines was successful.
+          description: Indicates the installation of prepackaged Timelines was successful.
           content:
             application/json:
               schema:
@@ -53,7 +54,7 @@ paths:
                   data:
                     $ref: '../model/components.schema.yaml#/components/schemas/ImportTimelineResult'
         '500':
-          description: Indicates the installation of prepackaged timelines was unsuccessful.
+          description: Indicates the installation of prepackaged Timelines was unsuccessful.
           content:
             application:json:
               schema:

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

@@ -15,12 +15,12 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: PatchTimeline
-      summary: Updates an existing timeline.
-      description: Updates an existing timeline. This API is used to update the title, description, date range, pinned events, pinned queries, and/or pinned saved queries of an existing timeline.
+      summary: Update a Timeline
+      description: Update an existing Timeline. You can update the title, description, date range, pinned events, pinned queries, and/or pinned saved queries of an existing Timeline.
       tags:
         - access:securitySolution
       requestBody:
-        description: The timeline updates along with the timeline ID and version.
+        description: The Timeline updates, along with the Timeline ID and version.
         required: true
         content:
           application/json:
@@ -38,7 +38,7 @@ paths:
                   $ref: '../model/components.schema.yaml#/components/schemas/SavedTimeline'
       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 draft Timeline was successfully created. In the event the user already has a draft Timeline, the existing draft Timeline is cleared and returned.
           content:
             application/json:
               schema:
@@ -56,7 +56,7 @@ paths:
                           timeline:
                             $ref: '../model/components.schema.yaml#/components/schemas/TimelineResponse'
         '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 draft Timeline.
           content:
             application/json:
               schema:

x-pack/plugins/security_solution/common/api/timeline/persist_favorite/persist_favorite_route.schema.yaml

@@ -15,11 +15,12 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: PersistFavoriteRoute
-      summary: Persists a given users favorite status of a timeline.
+      summary: Favorite a Timeline or Timeline template
+      description: Favorite a Timeline or Timeline template for the current user.
       tags:
         - access:securitySolution
       requestBody:
-        description: The required fields used to favorite a (template) timeline.
+        description: The required fields used to favorite a (template) Timeline.
         required: true
         content:
           application/json:

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

@@ -18,11 +18,12 @@ paths:
       x-labels: [serverless, ess]
       x-codegen-enabled: true
       operationId: PersistNoteRoute
-      summary: Persists a note to a timeline.
+      summary: Add or update a note
+      description: Add a note to a Timeline or update an existing note.
       tags:
         - access:securitySolution
       requestBody:
-        description: The note to persist or update along with additional metadata.
+        description: The note to add or update, along with additional metadata.
         required: true
         content:
           application/json: