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)
Problem
/telegraf/controller/reference/api/(#7314) documents one endpoint (GET /api/agents) and defers the full catalog to the authenticated, instance-served/api/docsreference.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:
/api/docsas the always-current complement.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)