Document the Tags as Code CRUD API (/api/tags)

[florent-leborgne]

Warning

Do not merge yet. The links below point to the dedicated Tags API reference pages, which 404 until the OAS bundle publishes for 9.5. Merge only once the Tags API reference is live. Currently checking with dev team

Summary

Adds a Manage tags programmatically section to the Tags page documenting the new /api/tags CRUD API ("Tags as code"), introduced in elastic/kibana#266220.

The section:

• Explains that tags can be created, read, updated, and deleted outside the Kibana UI, with the typical as-code / CI/CD / tooling use cases.
• Notes that /api/tags replaces the now-deprecated /api/saved_objects_tagging tag CRUD endpoints (confirmed deprecated in code with structured migrate metadata).
• Links to the API reference for the operations and schemas, rather than duplicating endpoint lists and request/response shapes (those are owned by the auto-generated reference at elastic.co/docs/api).
• Is scoped experimental since 9.5 (stack) and experimental (serverless), matching the route's availability.stability metadata.

Why this scope

The API ships with access: 'public' and full OpenAPI metadata (oas-tag:Tags, availability: { since: '9.5.0', stability: 'experimental' }), so its endpoints, parameters, and schemas will be auto-generated in the API reference. Reproducing them in narrative docs would duplicate the reference and drift. The narrative docs cover only what the reference can't: discoverability, the conceptual "what + why", and the deprecation/migration pointer.

Pending links (blocking merge)

The section links directly to the dedicated Tags API reference pages, which don't exist yet (they 404 today) and won't publish until the OAS bundle is regenerated for 9.5:

• Stateful: https://www.elastic.co/docs/api/doc/kibana/group/endpoint-tags
• Serverless: https://www.elastic.co/docs/api/doc/serverless/group/endpoint-tags

These are the correct slugs — the legacy routes' own deprecated.documentationUrl points at endpoint-tags. Verify they resolve before merging.

Blocking dependency: OAS generation

The /api/tags routes are public in code but are not yet present in either bundled spec on main (oas_docs/output/kibana.yaml, oas_docs/output/kibana.serverless.yaml). Until the tagging plugin's routes are captured into the OAS bundle, the API won't appear at elastic.co/docs/api. Action: confirm with the Kibana/as-code team that the tagging plugin is wired into OAS generation before/at the 9.5 cut.

Screenshots to add or update

None — the new section is text-only.

Refs #6682

[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: queued.

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

[github-actions]

🔍 Preview links for changed docs

• explore-analyze/find-and-organize/tags.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.

[benironside]

LGTM

[github-actions]

Docs review summary

Focus areas

• Style and clarity: Prose is concise, present tense, second person. One link-text nit on line 90 (see Nits).
• Jargon: CRUD and CI/CD are standard developer vocabulary, not Elastic-internal jargon; appropriate for this audience. {{kib}} substitution is consistent with the rest of the file.
• Frontmatter and applies_to: Section-level applies_to correctly uses stack: experimental 9.5 and serverless: experimental, matching valid keys and lifecycle values from the cumulative-docs reference. Page-level frontmatter is unchanged.
• Content type fit: The new section is a concise API-awareness addition to an existing how-to guide. The fit is appropriate.
• Parent issue satisfaction: Partially satisfied — see Notes.

Nits

• Line 90 — ([serverless](https://www.elastic.co/docs/api/doc/serverless/group/endpoint-tags)) uses bare serverless as link text. Per the accessibility guideline that link text must be descriptive (screen readers announce "link: serverless" with no destination context), consider:

  refer to the [Tags API reference](https://www.elastic.co/docs/api/doc/kibana/group/endpoint-tags) ([serverless version](https://www.elastic.co/docs/api/doc/serverless/group/endpoint-tags)).
  

Notes

• Issue Document the Tags as Code CRUD API at /api/tags #6682 gap — upsert semantics: The issue explicitly requested documentation of upsert semantics and a migration table from the deprecated /api/saved_objects_tagging routes. The PR covers the migration with a single sentence (line 88), but does not mention upsert or idempotency behavior. If /api/tags has meaningful upsert semantics that affect automation scripts (e.g., create-or-update by name), a short callout would close that remaining gap.
• The Vale warning on mapped_pages (line 2) is pre-existing and not introduced by this PR.
• The PR is correctly blocked on the OAS bundle publishing — no documentation concern there, just a merge-readiness dependency.

Generated by Docs review agent for issue #7038 · 35 AIC · ⌖ 8.43 AIC · ⊞ 10.7K · ◷

[kosabogi]

I left a comment with two questions rather than suggestions. Otherwise, LGTM.