Document Kibana API availability option for version and lifecycle tagging

[Copilot]

Plan for Adding Kibana API Availability Documentation

• Update kibana-api-docs-quickstart.md to emphasize versioning/lifecycle info

  • Add explicit guidance about including availability information in the "Make your docs changes" step
  • Include comprehensive documentation of the availability option with both fields explained
  • Add real-world example from the A2A route
  • Add note about API-level vs parameter-level documentation
  • Make it clear this is a required part of API documentation
  • Wrap examples in dropdown elements to save space
  • Fix dropdown rendering by moving them outside the important block

• Address feedback from review

  • Reverted changes to organize-annotate.md as requested
  • Consolidated all pertinent information into kibana-api-docs-quickstart.md
  • Used proper delimiter nesting (5 colons for dropdowns at tab-item level)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Update the API contribution docs for Kibana version and lifecycle tagging</issue_title>
<issue_description>## Context

We need to add version availability to new API endpoints in kibana by including the availability option. This is what powers the version badges and tech preview labels in the API docs (e.g. "Added in 9.2.0"). Without it, users have no way to know when an API landed or whether it's in tech preview or not.

We need to document it super clearly because it's something that devs can easily overlook in their PRs.

Example from the A2A route:

options: {
  tags: ['a2a', 'oas-tag:agent builder'],
  availability: {
    stability: 'experimental',
    since: '9.2.0',
  },
},

The values for stability are:

• experimental — tech preview, may change or be removed
• stable — GA (default if not specified)

Pages to update

https://github.com/elastic/docs-content/edit/main/contribute-docs/api-docs/organize-annotate.md: add a tab about how to do this in Kibana

https://github.com/elastic/docs-content/edit/main/contribute-docs/api-docs/kibana-api-docs-quickstart.md: be explicit about adding versioning/lifecycle info in ::::::{step} Make your docs changes

</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Update the API contribution docs for Kibana version and lifecycle tagging #5118

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[github-actions]

✅ Vale Linting Results

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.

[leemthompo]

@copilot One important thing to mention is that it's only available at the API endpoint level, not parameter level. For parameters, you have to write it manually in the description.

[Copilot]

@copilot One important thing to mention is that it's only available at the API endpoint level, not parameter level. For parameters, you have to write it manually in the description.

Added a note clarifying that the availability option is only available at the API/route level. For parameters, developers need to manually document version information in the description field. (65cc367)

[github-actions]

🔍 Preview links for changed docs

• contribute-docs/api-docs/kibana-api-docs-quickstart.md

[leemthompo]

@copilot let's forget about organize-annotate.md‎ for now, you can revert changes to that file, and add anything that might be pertinent from that to the Kibana quickstart for the time being

[Copilot]

@copilot let's forget about organize-annotate.md‎ for now, you can revert changes to that file, and add anything that might be pertinent from that to the Kibana quickstart for the time being

Reverted changes to organize-annotate.md and consolidated all the pertinent information into kibana-api-docs-quickstart.md. The quickstart now includes:

• Complete availability option documentation with both fields explained
• Full router.versioned.post example
• Real-world A2A route example
• Note about API-level vs parameter-level documentation

(aa4215c)

[leemthompo]

@copilot put the examples in dropdown to save space and be careful to use sufficiently deep delimiter numbering to avoid closing the wrong opening colon

:::{dropdown} Dropdown Title
Dropdown content
:::

[Copilot]

@copilot put the examples in dropdown to save space and be careful to use sufficiently deep delimiter numbering to avoid closing the wrong opening colon

...

Wrapped both examples in dropdown elements using 4-colon delimiters (::::) to properly nest them inside the 3-colon important block. Field descriptions are now shown first for quick reference, with the code examples collapsible. (b602213)

[leemthompo]

@copilot the url preview isn't looking great 😨

[Copilot]

@copilot the url preview isn't looking g...

Fixed! Moved the dropdowns outside the important block and changed them to use 5-colon delimiters. The important block now contains just the key information (field descriptions and the note), and the code examples are in collapsible dropdowns below it. (a04c589)