[Osquery] Enables OpenAPI documentation for 5 new Osquery 9.4 API endpoints

x-pack/platform/plugins/shared/osquery/common/api/model/schema/common_attributes.gen.ts

@@ -110,7 +110,7 @@ export type SavedQueryDescriptionOrUndefined = z.infer<typeof SavedQueryDescript
 export const SavedQueryDescriptionOrUndefined = SavedQueryDescription.nullable();
 
 /**
- * The ID of the pack you want to run, retrieve, update, or delete.
+ * The ID of the pack.
  */
 export type PackId = z.infer<typeof PackId>;
 export const PackId = z.string();

x-pack/platform/plugins/shared/osquery/common/api/model/schema/common_attributes.schema.yaml

@@ -100,7 +100,7 @@ components:
 
 
     PackId:
-      description: 'The ID of the pack you want to run, retrieve, update, or delete.'
+      description: 'The ID of the pack.'
       example: '3c42c847-eb30-4452-80e0-728584042334'
       type: string
 

x-pack/platform/plugins/shared/osquery/common/api/packs/packs.schema.yaml

@@ -142,9 +142,8 @@ paths:
         The copied pack is always created with `enabled` set to `false`.
       operationId: OsqueryCopyPacks
       x-codegen-enabled: true
-      #      TODO: Remove the empty x-labels array and uncomment the following line when feature flag is enabled
-      x-labels: [ ]
-      #      x-labels: [serverless, ess]
+      x-labels: [ serverless, ess ]
+      x-state: Generally available; Added in 9.4.0
       parameters:
         - name: id
           in: path
@@ -159,3 +158,29 @@ paths:
             application/json:
               schema:
                 $ref: './copy_pack.schema.yaml#/components/schemas/CopyPacksResponse'
+              examples:
+                copyPackExample:
+                  summary: Example response for copying a pack
+                  value:
+                    data:
+                      saved_object_id: '1c266590-381f-428c-878f-c80c1334f856'
+                      name: 'my_pack_copy'
+                      description: 'My pack'
+                      enabled: false
+                      queries:
+                        - id: 'ports'
+                          query: 'SELECT * FROM listening_ports;'
+                          interval: 60
+                          snapshot: true
+                          removed: false
+                          timeout: 120
+                          ecs_mapping:
+                            - key: 'client.port'
+                              value:
+                                field: 'port'
+                      shards: []
+                      policy_ids: []
+                      created_at: '2025-02-26T13:37:30.452Z'
+                      created_by: 'elastic'
+                      updated_at: '2025-02-26T13:37:30.452Z'
+                      updated_by: 'elastic'

x-pack/platform/plugins/shared/osquery/common/api/saved_query/saved_query.schema.yaml

@@ -139,9 +139,8 @@ paths:
         If the name already exists, a numeric suffix is added (e.g., `_copy_2`).
       operationId: OsqueryCopySavedQuery
       x-codegen-enabled: true
-      #      TODO: Remove the empty x-labels array and uncomment the following line when feature flag is enabled
-      x-labels: [ ]
-      #      x-labels: [serverless, ess]
+      x-labels: [ serverless, ess ]
+      x-state: Generally available; Added in 9.4.0
       parameters:
         - name: id
           in: path
@@ -156,3 +155,24 @@ paths:
             application/json:
               schema:
                 $ref: './copy_saved_query.schema.yaml#/components/schemas/CopySavedQueryResponse'
+              examples:
+                copySavedQueryExample:
+                  summary: Example response for copying a saved query
+                  value:
+                    data:
+                      saved_object_id: '42ba1280-2172-11ee-8523-5765fca79a3c'
+                      id: 'my_saved_query_copy'
+                      query: 'select * from uptime;'
+                      description: 'Saved query description'
+                      platform: 'linux,darwin'
+                      interval: '60'
+                      timeout: 120
+                      snapshot: true
+                      removed: false
+                      ecs_mapping:
+                        host.uptime:
+                          field: 'total_seconds'
+                      created_at: '2025-02-26T13:37:30.452Z'
+                      created_by: 'elastic'
+                      updated_at: '2025-02-26T13:37:30.452Z'
+                      updated_by: 'elastic'

x-pack/platform/plugins/shared/osquery/common/api/scheduled_results/get_scheduled_action_results.schema.yaml

@@ -86,7 +86,12 @@ components:
           queryName: 'uptime'
           queryText: 'select * from uptime;'
           timestamp: '2024-07-26T09:00:00.000Z'
-        edges: [{}]
+        edges:
+          - _id: 'result-001'
+            fields:
+              agent_id: '16d7caf5-efd2-4212-9b62-73dafc91fa13'
+              status: 'success'
+              rows_count: 5
         total: 10
         currentPage: 0
         pageSize: 20

x-pack/platform/plugins/shared/osquery/common/api/scheduled_results/get_scheduled_query_results.schema.yaml

@@ -27,4 +27,12 @@ components:
       example:
         data:
           total: 2
-          edges: [{}, {}]
+          edges:
+            - _id: 'row-001'
+              fields:
+                host.uptime:
+                  - '12345'
+            - _id: 'row-002'
+              fields:
+                host.uptime:
+                  - '67890'

x-pack/platform/plugins/shared/osquery/common/api/scheduled_results/scheduled_results.gen.ts

@@ -30,10 +30,25 @@ export type OsqueryGetScheduledActionResultsRequestQuery = z.infer<
   typeof OsqueryGetScheduledActionResultsRequestQuery
 >;
 export const OsqueryGetScheduledActionResultsRequestQuery = z.object({
+  /**
+   * The kuery to filter the results by.
+   */
   kuery: KueryOrUndefined.optional(),
+  /**
+   * The page number to return. The default is 1.
+   */
   page: PageOrUndefined.optional(),
+  /**
+   * The number of results to return per page. The default is 20.
+   */
   pageSize: PageSizeOrUndefined.optional(),
+  /**
+   * The field that is used to sort the results.
+   */
   sort: SortOrUndefined.optional(),
+  /**
+   * Specifies the sort order.
+   */
   sortOrder: SortOrderOrUndefined.optional(),
 });
 export type OsqueryGetScheduledActionResultsRequestQueryInput = z.input<
@@ -44,7 +59,13 @@ export type OsqueryGetScheduledActionResultsRequestParams = z.infer<
   typeof OsqueryGetScheduledActionResultsRequestParams
 >;
 export const OsqueryGetScheduledActionResultsRequestParams = z.object({
+  /**
+   * The schedule ID of the scheduled query.
+   */
   scheduleId: z.string(),
+  /**
+   * The execution count for this scheduled query run.
+   */
   executionCount: z.number().int(),
 });
 export type OsqueryGetScheduledActionResultsRequestParamsInput = z.input<
@@ -59,11 +80,29 @@ export type OsqueryGetScheduledQueryResultsRequestQuery = z.infer<
   typeof OsqueryGetScheduledQueryResultsRequestQuery
 >;
 export const OsqueryGetScheduledQueryResultsRequestQuery = z.object({
+  /**
+   * The kuery to filter the results by.
+   */
   kuery: KueryOrUndefined.optional(),
+  /**
+   * The page number to return. The default is 1.
+   */
   page: PageOrUndefined.optional(),
+  /**
+   * The number of results to return per page. The default is 20.
+   */
   pageSize: PageSizeOrUndefined.optional(),
+  /**
+   * The field that is used to sort the results.
+   */
   sort: SortOrUndefined.optional(),
+  /**
+   * Specifies the sort order.
+   */
   sortOrder: SortOrderOrUndefined.optional(),
+  /**
+   * The start date filter (ISO 8601) to narrow down results.
+   */
   startDate: z.string().optional(),
 });
 export type OsqueryGetScheduledQueryResultsRequestQueryInput = z.input<
@@ -74,7 +113,13 @@ export type OsqueryGetScheduledQueryResultsRequestParams = z.infer<
   typeof OsqueryGetScheduledQueryResultsRequestParams
 >;
 export const OsqueryGetScheduledQueryResultsRequestParams = z.object({
+  /**
+   * The schedule ID of the scheduled query.
+   */
   scheduleId: z.string(),
+  /**
+   * The execution count for this scheduled query run.
+   */
   executionCount: z.number().int(),
 });
 export type OsqueryGetScheduledQueryResultsRequestParamsInput = z.input<

x-pack/platform/plugins/shared/osquery/common/api/scheduled_results/scheduled_results.schema.yaml

@@ -12,56 +12,90 @@ paths:
         (pack name, query name/text, timestamp).
       operationId: OsqueryGetScheduledActionResults
       x-codegen-enabled: true
-      #      TODO: Remove the empty x-labels array and uncomment the following line when feature flag is enabled
-      x-labels: [ ]
-      #      x-labels: [serverless, ess]
+      x-labels: [ serverless, ess ]
+      x-state: Generally available; Added in 9.4.0
       parameters:
         - name: scheduleId
           in: path
           required: true
+          description: 'The schedule ID of the scheduled query.'
           schema:
             description: 'The schedule ID of the scheduled query.'
             type: string
             example: 'pack_my_pack_uptime'
         - name: executionCount
           in: path
           required: true
+          description: 'The execution count for this scheduled query run.'
           schema:
             description: 'The execution count for this scheduled query run.'
             type: integer
             example: 3
         - name: kuery
           in: query
           required: false
+          description: 'The kuery to filter the results by.'
           schema:
             $ref: '../model/schema/common_attributes.schema.yaml#/components/schemas/KueryOrUndefined'
         - name: page
           in: query
           required: false
+          description: 'The page number to return. The default is 1.'
           schema:
             $ref: '../model/schema/common_attributes.schema.yaml#/components/schemas/PageOrUndefined'
         - name: pageSize
           in: query
           required: false
+          description: 'The number of results to return per page. The default is 20.'
           schema:
             $ref: '../model/schema/common_attributes.schema.yaml#/components/schemas/PageSizeOrUndefined'
         - name: sort
           in: query
           required: false
+          description: 'The field that is used to sort the results.'
           schema:
             $ref: '../model/schema/common_attributes.schema.yaml#/components/schemas/SortOrUndefined'
         - name: sortOrder
           in: query
           required: false
+          description: 'Specifies the sort order.'
           schema:
             $ref: '../model/schema/common_attributes.schema.yaml#/components/schemas/SortOrderOrUndefined'
       responses:
         '200':
-          description: OK
+          description: Indicates a successful call.
           content:
             application/json:
               schema:
                 $ref: './get_scheduled_action_results.schema.yaml#/components/schemas/GetScheduledActionResultsResponse'
+              examples:
+                scheduledActionResultsExample:
+                  summary: Example scheduled action results response
+                  value:
+                    metadata:
+                      scheduleId: 'pack_my_pack_uptime'
+                      executionCount: 3
+                      packId: '42ba9c50-0cc5-11ed-aa1d-2b27890bc90d'
+                      packName: 'My Pack'
+                      queryName: 'uptime'
+                      queryText: 'select * from uptime;'
+                      timestamp: '2024-07-26T09:00:00.000Z'
+                    edges:
+                      - _id: 'result-001'
+                        fields:
+                          agent_id: '16d7caf5-efd2-4212-9b62-73dafc91fa13'
+                          status: 'success'
+                          rows_count: 5
+                    total: 10
+                    currentPage: 0
+                    pageSize: 20
+                    totalPages: 1
+                    aggregations:
+                      totalRowCount: 42
+                      totalResponded: 10
+                      successful: 9
+                      failed: 1
+                      pending: 0
 
   /api/osquery/scheduled_results/{scheduleId}/{executionCount}/results:
     get:
@@ -71,60 +105,82 @@ paths:
         for a specific scheduled query execution.
       operationId: OsqueryGetScheduledQueryResults
       x-codegen-enabled: true
-      #      TODO: Remove the empty x-labels array and uncomment the following line when feature flag is enabled
-      x-labels: [ ]
-      #      x-labels: [serverless, ess]
+      x-labels: [ serverless, ess ]
+      x-state: Generally available; Added in 9.4.0
       parameters:
         - name: scheduleId
           in: path
           required: true
+          description: 'The schedule ID of the scheduled query.'
           schema:
             description: 'The schedule ID of the scheduled query.'
             type: string
             example: 'pack_my_pack_uptime'
         - name: executionCount
           in: path
           required: true
+          description: 'The execution count for this scheduled query run.'
           schema:
             description: 'The execution count for this scheduled query run.'
             type: integer
             example: 3
         - name: kuery
           in: query
           required: false
+          description: 'The kuery to filter the results by.'
           schema:
             $ref: '../model/schema/common_attributes.schema.yaml#/components/schemas/KueryOrUndefined'
         - name: page
           in: query
           required: false
+          description: 'The page number to return. The default is 1.'
           schema:
             $ref: '../model/schema/common_attributes.schema.yaml#/components/schemas/PageOrUndefined'
         - name: pageSize
           in: query
           required: false
+          description: 'The number of results to return per page. The default is 20.'
           schema:
             $ref: '../model/schema/common_attributes.schema.yaml#/components/schemas/PageSizeOrUndefined'
         - name: sort
           in: query
           required: false
+          description: 'The field that is used to sort the results.'
           schema:
             $ref: '../model/schema/common_attributes.schema.yaml#/components/schemas/SortOrUndefined'
         - name: sortOrder
           in: query
           required: false
+          description: 'Specifies the sort order.'
           schema:
             $ref: '../model/schema/common_attributes.schema.yaml#/components/schemas/SortOrderOrUndefined'
         - name: startDate
           in: query
           required: false
+          description: 'The start date filter (ISO 8601) to narrow down results.'
           schema:
             description: 'The start date filter (ISO 8601) to narrow down results.'
             example: '2024-01-01T00:00:00Z'
             type: string
       responses:
         '200':
-          description: OK
+          description: Indicates a successful call.
           content:
             application/json:
               schema:
                 $ref: './get_scheduled_query_results.schema.yaml#/components/schemas/GetScheduledQueryResultsResponse'
+              examples:
+                scheduledQueryResultsExample:
+                  summary: Example scheduled query results response
+                  value:
+                    data:
+                      total: 2
+                      edges:
+                        - _id: 'row-001'
+                          fields:
+                            host.uptime:
+                              - '12345'
+                        - _id: 'row-002'
+                          fields:
+                            host.uptime:
+                              - '67890'