influxdata / influxdata/docs-v2

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

Open
#7,322 0 comments 0 reactions 2 assignees View on GitHub

@sanderson is already working on this.

Since Jun 11, 2026.

product:telegraf
Dominant language
JavaScript
Stars
82
Forks
326
Avg merge
1d 1h
Merged PRs (30d)
82

Description

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)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.