Skip to content

Telegraf Controller: add a static endpoint catalog to the API reference page #7322

@jstirnaman

Description

@jstirnaman

Problem

/telegraf/controller/reference/api/ (#7314) documents one endpoint (GET /api/agents) and defers the full catalog to the authenticated, instance-served /api/docs reference.

The instance reference is invisible to crawlers, RAG retrievers, and hosted assistants (including the docs site's own assistant). An agent grounded only in the docs site that asks "what endpoints does the Telegraf Controller API have?" hits a dead end: the retrievable answer is "check your instance."

Proposed change

Add a static endpoint catalog table to the API reference page:

  • Resource groups (agents, configs, tokens, users, labels, heartbeat, ...) × operations, with one-line descriptions.
  • Stamp it with the release version it was generated from (for example, "as of v0.0.7-beta") so staleness is visible, and keep /api/docs as the always-current complement.
  • Summary level only — request/response schemas stay in the instance reference until the API stabilizes enough to justify wiring the spec into the api-docs/ Hugo pipeline like other products.

Why

This gives every docs-site-grounded consumer (crawl corpora, RAG, the kapa.ai assistant) an extractable answer between releases, at low maintenance cost. Without it, future models learn the API's auth conventions but hallucinate its endpoint paths by analogy with other InfluxData APIs.

Related: #7314 (API reference page), #7321 (machine-readable spec endpoint)

Metadata

Metadata

Labels

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions