[Osquery] Enables OpenAPI documentation for 5 new Osquery 9.4 API endpoints by tomsonpl · Pull Request #262810 · elastic/kibana

tomsonpl · 2026-04-13T15:18:03Z

Summary

Enables OpenAPI documentation for the new Osquery 9.4 API endpoints introduced behind the feature flag. Now that the feature flag has been enabled in #262693, the API specs can be published to the official bundled documentation.

Changes

Enabled x-labels for new endpoints

Replaced empty x-labels: [] with x-labels: [serverless, ess] on the following endpoints that were previously gated behind the feature flag:
- POST /api/osquery/packs/{id}/copy — Copy an osquery pack
- POST /api/osquery/saved_queries/{id}/copy — Copy an osquery saved query
- GET /api/osquery/scheduled_results/{scheduleId}/{executionCount} — Get scheduled action results
- GET /api/osquery/scheduled_results/{scheduleId}/{executionCount}/results — Get scheduled query results
- GET /api/osquery/history — Get unified execution history
Removed associated TODO comments that were placeholder markers for the FF-gated state.

Added parameter-level descriptions to OpenAPI schemas

Added description fields at the parameter level (alongside the existing schema-level descriptions) for scheduled_results.schema.yaml and unified_history.schema.yaml. This ensures proper rendering in API documentation tools that read parameter-level metadata.

Endpoints added to public API documentation

Method	Path	Description
`GET`	`/api/osquery/history`	Get a unified, time-sorted history of live, rule-triggered, and scheduled osquery executions
`POST`	`/api/osquery/packs/{id}/copy`	Copy an osquery pack
`POST`	`/api/osquery/saved_queries/{id}/copy`	Copy an osquery saved query
`GET`	`/api/osquery/scheduled_results/{scheduleId}/{executionCount}`	Get scheduled action results (metadata)
`GET`	`/api/osquery/scheduled_results/{scheduleId}/{executionCount}/results`	Get scheduled query results (data rows)

Context

This is the documentation counterpart to #262693 which enabled the Osquery 9.4 feature flag. The endpoints themselves were already implemented and functional; this PR makes them visible in the official Kibana OpenAPI specification so they appear in public API docs and can be consumed by API clients and tooling.

Risk Matrix

Risk	Level	Mitigation
Runtime behavior change	None	Documentation-only change — no server code modified
API contract change	None	Endpoints already existed and were serving traffic; this only adds their OAS documentation
Breaking change	None	No existing API signatures are modified

Test plan

Verify the bundled OpenAPI YAML files are valid by loading them in an OpenAPI viewer (e.g., Swagger UI or Redocly)
Confirm all five new endpoints appear in both the ESS and Serverless bundled docs
Verify the generated .gen.ts files are consistent with the schema YAML (run code generation and confirm no diff)
Confirm CI passes — type checks, linting, and bundled doc validation

tomsonpl · 2026-04-13T18:10:53Z

/ci

elasticmachine · 2026-04-13T18:16:27Z

Pinging @elastic/security-defend-workflows (Team:Defend Workflows)

natasha-moore-elastic

Left a couple of suggestions, but looks good overall!
One thing that we should add to the new endpoints is x-state to indicate the lifecycle (Generally available) and version applicability (Added in 9.4.0).

natasha-moore-elastic · 2026-04-14T15:26:28Z

+          name: id
+          required: true
+          schema:
+            $ref: '#/components/schemas/PackId'


The description of this param is The ID of the pack you want to run, retrieve, update, or delete.
Could we update it to either include ...or copy, or to be more generic like The ID of the pack you want to perform the action on.

natasha-moore-elastic · 2026-04-14T15:32:24Z

      nullable: true
      type: string
+    UnifiedHistoryRow:
+      oneOf:


When rendered in bump, these show as two separate tabs with the same name (object-2)

Could we do something similar to this
https://github.com/elastic/kibana/blob/main/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml#L8599 so that when rendered the tabs have specific names:

natasha-moore-elastic · 2026-04-14T15:45:55Z

+                    data:
+                      edges:
+                        - {}
+                        - {}


Just checking these are supposed to be empty?

# Conflicts: # oas_docs/output/kibana.serverless.yaml # oas_docs/output/kibana.yaml # x-pack/platform/plugins/shared/osquery/docs/openapi/ess/osquery_api_2023_10_31.bundled.schema.yaml # x-pack/platform/plugins/shared/osquery/docs/openapi/serverless/osquery_api_2023_10_31.bundled.schema.yaml

tomsonpl · 2026-04-16T10:09:55Z

Thanks @natasha-moore-elastic, I applied the suggestions 👍

elasticmachine · 2026-04-17T09:19:13Z

⏳ Build in-progress, with failures

Failed CI Steps

Test Failures

[job] [logs] FTR Configs #129 / AgentBuilder Endpoints SML internal API POST /internal/agent_builder/sml/_attach attaches SML items and persists conversation attachment refs
[job] [logs] FTR Configs #94 / Serverless Observability - Deployment-agnostic Synthetics API integration tests SyntheticsAPITests PrivateLocationCreateMonitor handles auto upgrading policies
[job] [logs] FTR Configs #94 / Serverless Observability - Deployment-agnostic Synthetics API integration tests SyntheticsAPITests PrivateLocationCreateMonitor handles auto upgrading policies

History

💔 Build #428810 failed 80766ab
💔 Build #426911 failed 31d4294

cc @tomsonpl

szwarckonrad

LGTM, good job! Clean PR, everything looks correct. The x-labels flip, x-state annotations, parameter-level descriptions, discriminator on UnifiedHistoryRow, and the improved examples all look solid.

kibanamachine · 2026-04-17T16:38:56Z

Starting backport for target branches: 9.4

https://github.com/elastic/kibana/actions/runs/24576089641

kibanamachine · 2026-04-17T16:49:00Z

💔 All backports failed

Status	Branch	Result
❌	9.4	Backport failed because of merge conflicts

Manual backport

To create the backport manually run:

node scripts/backport --pr 262810

Questions ?

Please refer to the Backport tool documentation

tomsonpl added 3 commits April 13, 2026 17:16

[Osquery] Enable openapi docs

2f0e8b1

[Osquery] Enable openapi docs

240fb3e

Merge branch 'main' into oas-docs-osquery

2b5df2f

tomsonpl changed the title ~~Oas docs osquery~~ [Osquery] Enables OpenAPI documentation for 5 new Osquery 9.4 API endpoints Apr 13, 2026

tomsonpl requested a review from szwarckonrad April 13, 2026 18:16

tomsonpl marked this pull request as ready for review April 13, 2026 18:16

tomsonpl requested a review from a team as a code owner April 13, 2026 18:16

tomsonpl requested a review from pzl April 13, 2026 18:16

tomsonpl self-assigned this Apr 13, 2026

tomsonpl added release_note:skip Skip the PR/issue when compiling release notes Team:Defend Workflows “EDR Workflows” sub-team of Security Solution Osquery backport:version Backport to applied version labels v9.4.0 labels Apr 13, 2026

Changes from make api-docs

31d4294

elastic-vault-github-plugin-prod Bot requested a review from a team as a code owner April 13, 2026 18:44

natasha-moore-elastic approved these changes Apr 14, 2026

View reviewed changes

tomsonpl added 2 commits April 16, 2026 11:42

[Osquery] Apply review comments

ad584b8

Changes from make api-docs

80766ab

elastic-vault-github-plugin-prod Bot requested a review from a team as a code owner April 16, 2026 10:54

tomsonpl and others added 3 commits April 17, 2026 09:29

Merge branch 'main' into oas-docs-osquery

0178edf

[Osquery] Fix issues in schemas

d852a1d

Changes from make api-docs

4cd0b2c

Merge branch 'main' into oas-docs-osquery

0274008

florent-leborgne approved these changes Apr 17, 2026

View reviewed changes

szwarckonrad approved these changes Apr 17, 2026

View reviewed changes

tomsonpl merged commit 3259c92 into elastic:main Apr 17, 2026
18 checks passed

kibanamachine added the v9.5.0 label Apr 17, 2026

tomsonpl added backport:skip This PR does not require backporting and removed backport:version Backport to applied version labels labels Apr 17, 2026

This was referenced Apr 20, 2026

chore: remove trigger unsupported ftr tests #264105

Merged

[scout] migrate FTR logstash api tests #262953

Merged

This was referenced Apr 30, 2026

[OAS][Detection Engine] Clean up remaining errors #266228

Merged

[Fleet] Validate SSL certificate paths for whitespace #266365

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

[Osquery] Enables OpenAPI documentation for 5 new Osquery 9.4 API endpoints#262810
tomsonpl merged 11 commits intoelastic:mainfrom
tomsonpl:oas-docs-osquery

tomsonpl commented Apr 13, 2026 •

edited by kibanamachine

Loading

Uh oh!

tomsonpl commented Apr 13, 2026

Uh oh!

elasticmachine commented Apr 13, 2026

Uh oh!

natasha-moore-elastic left a comment

Uh oh!

natasha-moore-elastic Apr 14, 2026

Uh oh!

natasha-moore-elastic Apr 14, 2026

Uh oh!

natasha-moore-elastic Apr 14, 2026

Uh oh!

tomsonpl commented Apr 16, 2026

Uh oh!

elasticmachine commented Apr 17, 2026

Uh oh!

szwarckonrad left a comment

Uh oh!

Uh oh!

kibanamachine commented Apr 17, 2026

Uh oh!

kibanamachine commented Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Conversation

tomsonpl commented Apr 13, 2026 • edited by kibanamachine Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Endpoints added to public API documentation

Context

Risk Matrix

Test plan

Uh oh!

tomsonpl commented Apr 13, 2026

Uh oh!

elasticmachine commented Apr 13, 2026

Uh oh!

natasha-moore-elastic left a comment

Choose a reason for hiding this comment

Uh oh!

natasha-moore-elastic Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

natasha-moore-elastic Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

natasha-moore-elastic Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

tomsonpl commented Apr 16, 2026

Uh oh!

elasticmachine commented Apr 17, 2026

⏳ Build in-progress, with failures

Failed CI Steps

Test Failures

History

Uh oh!

szwarckonrad left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kibanamachine commented Apr 17, 2026

Uh oh!

kibanamachine commented Apr 17, 2026

💔 All backports failed

Manual backport

Questions ?

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

tomsonpl commented Apr 13, 2026 •

edited by kibanamachine

Loading