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

Paginate list results

List endpoints return one page of items at a time, with the items in data and the paging values in total, page, and limit. Use the page and limit query parameters to choose the page:

  • page: the page number, starting at 1. Default: 1.
  • limit: the number of items per page. Default: 10. There is no maximum. limit=0 returns every item in one response.

A limit that is not a whole number of zero or more, such as -1, 1.5, or all, returns 400 Bad Request with the message limit must be a non-negative integer.

The following endpoints are paginated:

  • GET /api/agents
  • GET /api/configs
  • GET /api/config-groups
  • GET /api/labels
  • GET /api/reporting-rules
  • GET /api/tokens

The following example retrieves every label in one request:

curl --request GET \
  "https://
TELEGRAF_CONTROLLER_HOST
/api/labels?limit=0" \
  --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

limit=0 returns the whole collection in one response. On a large fleet, page through agents and configurations with page and limit instead.

GET /api/security-advisories (Telegraf Enterprise) uses its own range: limit accepts 1 to 100 and defaults to 25.

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!