---
title: Telegraf Controller API
description: Use the Telegraf Controller HTTP API to manage agents, configurations, and tokens programmatically. Learn how to authenticate API requests and explore the interactive API reference served by your Telegraf Controller instance.
url: https://docs.influxdata.com/telegraf/controller/reference/api/
estimated_tokens: 779
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/reference/api/
date: '2026-06-24T05:47:49-07:00'
lastmod: '2026-06-24T05:47:49-07:00'
---

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](/telegraf/controller/tokens/).
Include the token in the `Authorization` header using the `Bearer` or `Token`scheme:

#### Bearer ####

```
Authorization: Bearer tc-apiv1_xxxxxx
```

```
Authorization: Token tc-apiv1_xxxxxx
```

A token’s [permissions](/telegraf/controller/reference/authentication-authorization/)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](/telegraf/controller/tokens/create/).
For more ways to use tokens, including with Telegraf agents and heartbeat
requests, see [Use API tokens](/telegraf/controller/tokens/use/).

> [!Note]
> If authentication is disabled for an endpoint, requests to that endpoint do
> not require a token. See[Endpoint authentication](/telegraf/controller/reference/authentication-authorization/#endpoint-authentication)for details on configuring authentication requirements per endpoint.

## Make an API request

The following example uses [cURL](https://curl.se/) to list agents with the`GET /api/agents` endpoint:

```bash
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.

> [!Note]
> 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.

#### Related

* [Use API tokens](/telegraf/controller/tokens/use/)
* [Create an API token](/telegraf/controller/tokens/create/)
* [Authentication and authorization](/telegraf/controller/reference/authentication-authorization/)