The Telflo API's endpoints, the access each one requires, and its limits.
The Telflo API is a REST API served under /api/v1/public. It is what the Telflo CLI uses, and any HTTP client can call it. Requests carry a bearer credential of one of two kinds:
An API token from a service account, a value starting with tf_. The request acts as the token's organization and its service account, a Contributor, with the read or write access the token was created with.
A session obtained by telflo login. The request acts as you, in the organization you chose when you approved the login, and the CLI adds an X-Telflo-Org header naming that organization. A session can do what your role allows.
Authorization: Bearer tf_...
The interactive reference, linked as Telflo API from Settings > Service Accounts, lists every endpoint with its request and response bodies.
Paths are relative to /api/v1/public. Read endpoints work with every token; Write endpoints require a token created with Allow write access. Write access includes read access, and a session has both.
Confirms the credential: returns the organization ID, the identity's name (a token's name, or your email address), the granted access, and kind, either service_account or user.
Lists the configurations visible to the caller, most recently updated first: its own, and the organization's published ones. Each entry includes the collector distribution, the latest version number, and the published version number.
GET /configurations/{id}
Read
Reads one configuration with the YAML of its latest version.
GET /configurations/{id}/versions
Read
Lists a configuration's versions, newest first, each with its status (draft or published), collector version, distribution, description, and dates. No YAML.
GET /configurations/{id}/versions/{n}
Read
Reads one version with its YAML.
POST /configurations
Write
Creates a configuration and its version 1 as a draft. Body: name, yaml, and optionally collector_distribution. The YAML is stored without validation. Only otelcol-contrib, the default, is currently offered through the API; any other value, including clickstack, is rejected with 422. The distribution is locked from then on.
PATCH /configurations/{id}
Write
Renames a configuration or changes its description.
POST /configurations/{id}/versions
Write
Appends a version. Body: yaml, and optionally description. The new version inherits the latest version's collector version.
PATCH /configurations/{id}/versions/{n}
Write
Edits a draft version's yaml or collector_version. Add ?validate=true to validate the result first: invalid YAML is rejected with 422, and a validator outage answers 503; in both cases nothing is saved. A published version cannot be edited; the request is refused with 409.
POST /configurations/{id}/versions/{n}/publish
Write
Publishes a version, the same as Publish in the editor. Publishing an already published version returns the same result.
GET /configurations/{id}/versions/{n}/validation-pipelines
Read
Lists the validation rules saved on a version, what the Testing panel's Validation sub-tab shows, grouped by pipeline. Each rule reports whether it is api_owned, that is, saved through the API.
PUT /configurations/{id}/versions/{n}/validation-pipelines/{pipeline}
Write
Saves a set of rules for one pipeline of a version. Body: signal_type, rules (1 to 20), and optionally name. Rules saved earlier through the API are replaced; rules added by hand in the app are kept. A new set without a name is called API tests — <pipeline>.
Validates collector YAML on a real collector. Body: yaml, and optionally version and distribution (otelcol-contrib only). Returns valid, version, and a list of errors, each with a message and the component_path it refers to.
POST /ottl/lint
Read
Parses every OTTL expression with the real OTTL grammar. Body: either yaml, a whole collector configuration, or context with conditions, statements, or value_expressions. Returns valid, ottl_version, checked, one item per expression with its location in the YAML, error, and note, and a skipped list for expressions the linter cannot judge. At most 200 expressions per request.
Starts a pipeline test. Body: configuration_id with version_number, or yaml; sample; signal_type; target_pipeline; duration_seconds (1 to 60, default 5); optionally collector_version and collector_distribution; and either rules (1 to 20) or use_saved_rules to run the version's saved rules. Answers 202 with the run's id and status Queued. $orgvar: tokens are not substituted.
GET /testing/runs/{id}
Read
Reads a run: status (Queued, Running, Success, Fail, or Error), success, the collector's stderr, and, once finished, the per-rule validation_results. Poll until the status is final. A run the testing service refused to start ends in Error with stderr beginning The test was never executed: followed by the service's reason, for example that the requested collector version is not installed on the test runner.
GET /testing/runs/{id}/output
Read
Returns the collector's output as plain text once the run has finished.
Lists the organization's server and Kubernetes supervisor fleets, newest first. Kubernetes bridge fleets are not exposed.
POST /fleets
Write
Creates a fleet and issues its tokens. Body: label, type (server-supervisor or kubernetes-supervisor), and optionally expires_in (180d, 1y, 2y, or never, the default), which sets the runtime fleet token's lifetime for a server fleet; a Kubernetes supervisor fleet's token does not expire. Token values are not returned.
POST /fleets/{id}/install
Write
Composes the command that installs a collector into the fleet, the same as the app's install and Deploy dialogs. Body: platform (docker or linux for a server fleet, kubernetes for a Kubernetes supervisor fleet), optionally deployment_id, and platform options: server_name for Docker; arch, root_deploy_path, and systemd for Linux; and env values for the configuration's environment variables. Without deployment_id, a server fleet installs into its Default deploy group; a Kubernetes supervisor fleet must name the group when it has more than one, and cannot produce a command until it has at least one. Returns the command, the connection details it embeds, including the fleet's token for Docker and Linux, the install or values URL and its expiry, and notes.
GET /fleets/{id}/deployments
Read
Lists a fleet's deploy groups, by name, with their role, replicas, namespace, and assigned configuration and version.
GET /fleets/{id}/deployments/{id}
Read
Reads one deploy group.
POST /fleets/{id}/deployments
Write
Creates a deploy group in a fleet, assigned to a published version. Body: name, configuration_id, and version_number; for a Kubernetes supervisor fleet also role (node, cluster, or gateway) and optionally replicas and namespace.
PATCH /fleets/{id}/deployments/{id}
Write
Changes a deploy group's name, its assigned configuration_id and version_number, its replicas, or its namespace, or clears the assignment with a null configuration_id.
A deploy group is called a deployment in the API. A version assigned to a deploy group must be published first, deploy group names are unique within a fleet, and a deploy group's role cannot be changed after creation. Fleet labels are unique within the organization, and the organization's fleet limit applies to fleets created through the API. The install command for a server fleet's Docker platform includes the deploy group's volume mounts.
Lists the public flows in gallery order, without YAML: slug, name, summary, source, author, signals, tags, collector version, and distribution. Flows are not organization-scoped.
GET /flows/{slug}
Read
Reads one flow, adding its description and YAML. Flows are listed whatever their distribution, so a flow built for ClickStack reports clickstack even though POST /configurations accepts only otelcol-contrib; create a configuration from such a flow on otelcol-contrib, as telflo config create does.
A session request is missing the X-Telflo-Org header, or names something other than an organization ID.
401
The credential is missing, revoked, or expired, or the token's service account was removed from the organization.
403
The token lacks the required access, reported as This endpoint requires the 'write' claim; a session names an organization you are not an active member of, reported as You are not an active member of this organization; a session's role does not allow the change; or the caller may not change the resource.
404
The resource does not exist or is not visible to the caller, such as another member's draft, or a test run's output before the run has finished.
409
The version is published and cannot be edited, or a deploy group with that name already exists.
413
The request body or the test sample is over 1 MB.
422
The body is invalid: an unknown field, an unpublished version assigned to a deploy group, a distribution other than otelcol-contrib, a role that does not match the fleet type, a pipeline the configuration does not have, or a rule the sandbox rejects.
429
The credential is over its request limit.
501
The endpoint is not yet available.
502
The API could not reach the fleet service, or the web app could not reach the API, reported as Telflo API service unavailable. Retry after a pause.
503
The validator, OTTL linter, or testing sandbox is unavailable, or fleet creation and collector installation are not configured on the server. For validation, the response says the YAML was not checked and nothing was saved.
See Service accounts for creating tokens and the service-account model, and CLI for the command-line client.
