General Information

Kapacitor provides an HTTP API on port 9092 by default.
With the API you can control which tasks are executing, query status of tasks and manage recordings etc.

Each section below defines the available API endpoints and there inputs and outputs.

All requests are versioned and namespaced using the base path /kapacitor/v1/.

Response Codes

All requests can return these response codes:

HTTP Response Code

Meaning

2xx

The request was a success, content is dependent on the request.

4xx

Invalid request, refer to error for what it wrong with the request. Repeating the request will continue to return the same error.

5xx

The server was unable to process the request, refer to the error for a reason. Repeating the request may result in a success if the server issue has been resolved.

Errors

All requests can return JSON in the following format to provide more information about a failed request.

{
"error" : "error message"
}

Query Parameters vs JSON body

To make using this API a consistent and easy experience we follow one simple rule for when extra information
about a request is found in the query parameters of the URL or when they are part of the submitted JSON body.

Query parameters are used only for GET requests and all other requests expect parameters to be specified in the JSON body.

NOTE: The /kapacitor/v1/write endpoint is the one exception to this rule since Kapacitor is compatible with the InfluxDB /write endpoint.

Links

When creating resources in Kapacitor the API server will return a link object with an href of the resource.
Clients should not need to perform path manipulation in most cases and can use the links provided from previous calls.

IDs

The API allows the client to specify IDs for the various resources.
This way you can control the meaning of the IDs.
If you do not specify an ID a random UUID will be generated for the resource.

All IDs must match this regex ^[-\._\p{L}0-9]+$, which is essentially numbers, unicode letters, ‘-’, ‘.’ and ‘_‘.

Writing Data

Kapacitor can accept writes over HTTP using the line protocol.
This endpoint is identical in nature to the InfluxDB write endpoint.

Query Parameter

Purpose

db

Database name for the writes.

rp

Retention policy name for the writes.

NOTE: Kapacitor scopes all points by their database and retention policy.
This means you MUST specify the rp for writes or Kapacitor will not know which retention policy to use.

Templates

You can also define a task templates.
A task template is defined by a template TICKscript, and a task type.

Define Templates

To define a template POST to the /kapacitor/v1/templates endpoint.
If a template already exists then use the PATCH method to modify any property of the template.

Define a template using a JSON object with the following options:

Property

Purpose

id

Unique identifier for the template. If empty a random ID will be chosen.

type

The template type: stream or batch.

script

The content of the script.

When using PATCH, if any option is missing it will be left unmodified.

Updating Templates

When updating an existing template all associated tasks are reloaded with the new template definition.
The first error if any is returned when reloading associated tasks.
If an error occurs, any task that was updated to the new definition is reverted to the old definition.
This ensures that all associated tasks for a template either succeed or fail together.

As a result, you will not be able to update a template if it introduces a breaking change in the TICKscript.
In order to update a template in a breaking way you have two options:

Create a new template and reassign each task to the new template updating the task vars as needed.

If the breaking change is forward compatible (i.e. adds a new required var), first update each task with the needed vars,
then update the template once all tasks are ready.

Response

NOTE: If the pattern does not match any templates an empty list will be returned, with a 200 success.

Recordings

Kapacitor can save recordings of data and replay them against a specified task.

Start Recording

There are three methods for recording data with Kapacitor:
To create a recording make a POST request to the /kapacitor/v1/recordings/METHOD endpoint.

Method

Description

stream

Record the incoming stream of data.

batch

Record the results of the queries in a batch task.

query

Record the result of an explicit query.

The request returns once the recording is started and does not wait for it to finish.
A recording ID is returned to later identify the recording.

Stream

Parameter

Purpose

id

Unique identifier for the recording. If empty a random one will be chosen.

task

ID of a task, used to only record data for the DBRPs of the task.

stop

Record stream data until stop date.

Batch

Parameter

Purpose

id

Unique identifier for the recording. If empty a random one will be chosen.

task

ID of a task, records the results of the queries defined in the task.

start

Earliest date for which data will be recorded. RFC3339Nano formatted.

stop

Latest date for which data will be recorded. If not specified uses the current time. RFC3339Nano formatted data.

Query

Parameter

Purpose

id

Unique identifier for the recording. If empty a random one will be chosen.

type

Type of recording, stream or batch.

query

Query to execute.

cluster

Name of a configured InfluxDB cluster. If empty uses the default cluster.

NOTE: A recording itself is typed as either a stream or batch recording and can only be replayed to a task of a corresponding type.
Therefore when you record the result of a raw query you must specify the type recording you wish to create.

If true, use the times in the recording, otherwise adjust times relative to the current time.

clock

fast

One of fast or real. If real wait for real time to pass corresponding with the time in the recordings. If fast replay data without delay. For example, if clock is real then a stream recording of duration 5m will take 5m to replay.

Replay data without Recording

It is also possible to replay data directly without recording it first.
This is done by issuing a request similar to either a batch or query recording
but instead of storing the data it is immediately replayed against a task.
Using a stream recording for immediately replaying against a task is equivalent to enabling the task
and so is not supported.

Method

Description

batch

Replay the results of the queries in a batch task.

query

Replay the results of an explicit query.

Batch

Parameter

Default

Purpose

id

random

Unique identifier for the replay. If empty a random one will be chosen.

task

ID of a task, replays the results of the queries defined in the task against the task.

start

Earliest date for which data will be replayed. RFC3339Nano formatted.

stop

now

Latest date for which data will be replayed. If not specified uses the current time. RFC3339Nano formatted data.

recording-time

false

If true, use the times in the recording, otherwise adjust times relative to the current time.

clock

fast

One of fast or real. If real wait for real time to pass corresponding with the time in the recordings. If fast replay data without delay. For example, if clock is real then a stream recording of duration 5m will take 5m to replay.

Query

Parameter

Default

Purpose

id

random

Unique identifier for the replay. If empty a random one will be chosen.

task

ID of a task, replays the results of the queries against the task.

query

Query to execute.

cluster

Name of a configured InfluxDB cluster. If empty uses the default cluster.

recording-time

false

If true, use the times in the recording, otherwise adjust times relative to the current time.

clock

fast

One of fast or real. If real wait for real time to pass corresponding with the time in the recordings. If fast replay data without delay. For example, if clock is real then a stream recording of duration 5m will take 5m to replay.

Configuration

You can set configuration overrides via the API for certain sections of the config.
The overrides set via the API always take precedent over what may exist in the configuration file.
The sections available for overriding include the InfluxDB clusters and the alert handler sections.

The intent of the API is to allow for dynamic configuration of sensitive credentials without requiring that the Kapacitor process be restarted.
As such, it is recommended to use either the configuration file or the API to manage these configuration sections, but not both.
This will help to eliminate any confusion that may arise as to the source of a given configuration option.

Enabling/Disabling Configuration Overrides

By default the ability to override the configuration is enabled.
If you do not wish to enable this feature it can be disabled via the config-override configuration section.

[config-override]
enabled = false

If the config-override service is disabled then the relevant API endpoints will return 403 forbidden errors.

Recovering from bad configuration

If somehow you have created a configuration that causes Kapacitor to crash or otherwise not function,
you can disable applying overrides during startup with the skip-config-overrides top level configuration option.

# This configuration option is only a safe guard and should not be needed in practice.
skip-config-overrides = true

This allows you to still access the API to fix any unwanted configuration without applying that configuration during statup.

NOTE: It is probably easiest and safest to set this option as an environment variable KAPACITOR_SKIP_CONFIG_OVERRIDES=true, since it is meant to be temporary.
That way you do not have to modify your on disk configuration file or accidentally leave it in place causing issues later on.

Retrieving the current configuration

To retrieve the current configuration perform a GET request to the desired path.
The returned configuration will be the merged values from the configuration file and what has been stored in the overrides.
The returned content will be JSON encoded version of the configuration objects.

All sensitive information will not be returned in the request body.
Instead a boolean value will be in its place indicating whether the value is empty or not.
A list of which options are redacted is returned for each element.

Response

Code

Meaning

200

Success

Testing a service

To test a service make a POST request to the /kapacitor/v1/service-tests/<service name> endpoint.
The contents of the POST body depend on the service in test.
To determine the available options use a GET request to the same endpoint.
The returned options are also the defaults.