Document kuery (KQL) filtering and improve Fleet API page structure

[charlotte-hoblik]

Summary

Adds KQL filtering guidance to the Fleet API page and brings the page in line with the how-to content type. Closes #3401.

Connected issue: #3401

kuery / KQL filtering (the issue)

• New Filter results with KQL section: which list endpoints accept kuery, the saved-object field-prefix rule, a verified package_policies example, and links to the KQL reference. The API reference names kuery but never explains it or links out, this is the missing on-ramp.

Structure and navigation (applied the Elastic docs skills)

• Rewrote the page opening to state purpose and scope, and added a description to the frontmatter (no longer duplicated by the intro).
• Added a Before you begin prerequisites section, plus Next steps and Related pages sections.
• Folded the standalone Authentication section into the prerequisites.

Copy edits throughout

• Active voice, concision, and punctuation; removed the relative-time word "currently"; replaced a directional "previous example" reference with a direct link; fixed an unclosed quote in a curl example.

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used:
Claude Opus 4.8
Elastic docs review skills

[github-actions]

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

• Review docs changes (docs-review). Status: not started.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

[github-actions]

🔍 Preview links for changed docs

• reference/fleet/fleet-api-docs.md

[github-actions]

✅ Elastic Docs Style Checker (Vale)

No issues found on modified lines!

---

The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale.

[bmorelli25]

I don't think this wording aligns with our guidance on referring to apps and pages.

[vishaangelova]

You mean this one: https://www.elastic.co/docs/contribute-docs/style-guide/ui-writing#referring-to-apps-and-pages

[bmorelli25]

I'm pretty sure this isn't true. Agents and enrollment tokens are not saved objects. They are stored in .fleet-* system indices so they must be referenced directly with no saved object prefix.

Your example for package policies works in [redacted] test cluster (I'll share w/you on Slack).

GET kbn:/api/fleet/package_policies?kuery=ingest-package-policies.package.name:activemq

✅

{
  "items": [
    {
      "id": "9xxxxa3-b6b2-4xxx-8f20-bb9822xxxxxe",
      "version": "WxxxxxxxxxQ==",
      "name": "activemq-1",
...

However, appending the saved object type to an agent call does not work:

GET kbn:/api/fleet/agents?kuery=ingest-agents.status:online

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "[request query.kuery]: KQLSyntaxError: This key 'ingest-agents.status' does NOT exist in fleet-agents saved object index patterns"
}

Excluding the saved object type from an agent call does work:

GET kbn:/api/fleet/agents?kuery=status:online

✅

{
  "items": [
    {
      "id": "3xxxx1-4a0a-4b00-bxxxx20xxxxx9d4",
      "type": "PERMANENT",
      "active": true,
...

[bmorelli25]

@vishaangelova keep me honest here

[vishaangelova]

Ok, so actually only these two Fleet endpoints are backed by saved objects:

• Agent policies (GET /api/fleet/agent_policies): stored as a fleet-agent-policies saved object, or, on deployments where space awareness is off, as the legacy ingest-agent-policies saved object (#1 and #2).
  • Use fleet-agent-policies.<field> in the KQL prefix; the legacy ingest-agent-policies.<field> also works because Fleet normalizes either prefix at runtime (#3)
• Package policies (GET /api/fleet/package_policies): stored as a fleet-package-policies saved object, or, on deployments where space awareness is off, as the legacy ingest-package-policies saved object (#1, and #2).
  • Use fleet-package-policies.<field>, but the legacy ingest-package-policies.<field> also works for the same reason as above (#3).

Agents (GET /api/fleet/agents) are stored in the .fleet-agents ES system index (#1). So these should be referenced without a prefix (e.g., status:online). However, here fleet-agents.status:online also works because Fleet strips it from the kuery (#2), but ingest-agents. does not exist, and that returns an error.

Enrollment API keys (GET /api/fleet/enrollment_api_keys) are stored in the .fleet-enrollment-api-keys ES system index (#1), but here no prefix should be used as the kuery is passed straight through to the index search (e.g., policy_id:"<policy-id>").

[bmorelli25]

This is the same link that's right above this section. I'm not sure how useful it is to list it twice.