Telegraf Controller API

Telegraf Controller provides an HTTP API for managing agents, configurations, tokens, and other resources programmatically. Use the API to integrate Telegraf Controller with your own tools and automation.

API endpoints are served under the /api base path of your Telegraf Controller instance. For example, if Telegraf Controller runs at http://telegraf_controller.example.com, the agents endpoint is http://telegraf_controller.example.com/api/agents. By default, Telegraf Controller serves the API on port 8888.

Authenticate API requests

External API clients authenticate with an API token. Include the token in the Authorization header using the Bearer or Token scheme:

Bearer Token

Authorization: Bearer tc-apiv1_xxxxxx
Authorization: Token tc-apiv1_xxxxxx

A token’s permissions determine which endpoints and operations the request can access. Requests made with a token that lacks the required permissions are rejected with an authorization error.

To create a token, see Create API tokens. For more ways to use tokens, including with Telegraf agents and heartbeat requests, see Use API tokens.

If authentication is disabled for an endpoint, requests to that endpoint do not require a token. See Endpoint authentication for details on configuring authentication requirements per endpoint.

Make an API request

The following example uses cURL to list agents with the GET /api/agents endpoint:

curl --request GET \
  "https://
TELEGRAF_CONTROLLER_HOST
/api/agents" \
  --header "Authorization: Bearer 
TELEGRAF_CONTROLLER_TOKEN
"

Replace the following:

  • TELEGRAF_CONTROLLER_HOST: the host and port of your Telegraf Controller instance
  • TELEGRAF_CONTROLLER_TOKEN: your Telegraf Controller API token

Explore the interactive API reference

Each Telegraf Controller instance serves a complete, interactive API reference at the /api/docs endpoint. For example:

https://
TELEGRAF_CONTROLLER_HOST
/api/docs

Replace TELEGRAF_CONTROLLER_HOST with the host and port of your Telegraf Controller instance.

The interactive reference documents every available endpoint, including request parameters, request and response schemas, and required permissions. Use it to browse endpoints and try requests directly against your instance.

The /api/docs endpoint requires authentication. Log in to Telegraf Controller in your browser before opening the interactive reference. Telegraf Controller serves the reference from your running instance, so the documented endpoints always match your installed version.

Download the OpenAPI document

Telegraf Controller also serves the OpenAPI document that describes its API as JSON and as YAML:

https://
TELEGRAF_CONTROLLER_HOST
/api/docs/openapi.json
https://
TELEGRAF_CONTROLLER_HOST
/api/docs/openapi.yaml

Use the document to generate API clients, import the API into tools such as Postman, or compare API changes between Telegraf Controller versions. Like the interactive reference, the document describes the endpoints of your running instance, so it always matches your installed version.

Both URLs require authentication. In a browser, log in to Telegraf Controller first. From the command line or a script, include an API token in the Authorization header. The following example uses cURL to download the YAML document:

curl --request GET \
  "https://
TELEGRAF_CONTROLLER_HOST
/api/docs/openapi.yaml" \
  --header "Authorization: Bearer 
TELEGRAF_CONTROLLER_TOKEN
" \
  --output telegraf-controller-openapi.yaml

Replace the following:

  • TELEGRAF_CONTROLLER_HOST: the host and port of your Telegraf Controller instance
  • TELEGRAF_CONTROLLER_TOKEN: your Telegraf Controller API token

Was this page helpful?

Thank you for your feedback!