| 2xx | The request was a success, content is dependent on the request. |
| 4xx | Invalid request, refer to error for what is 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.
```json
{ "error" : "error message" }
```
### Query parameters vs JSON body
Query parameters are used only for GET requests.
All other requests expect parameters 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.
{{% /note %}}
### Links
When creating resources, the Kapacitor API server returns a `link` object with an `href` of the resource.
Clients should be able to use the links provided from previous calls without any path manipulation.
### IDs
To give you control over IDs, the Kapacitor API lets the client specify IDs for various resources.
If you do not specify an ID, Kapacitor generates a random UUID for the resource.
All IDs must match the following regular expression (essentially numbers, unicode letters, `-`, `.` and `_`.):
```
^[-\._\p{L}0-9]+$`
```
### Backwards compatibility
Currently, Kapacitor is in 1.x release with a guarantee that all new releases
will be backwards compatible with previous releases.
This applies directly to the API. Updates may be made to the API, but existing
endpoints will not be changed in backwards-incompatible ways in 1.x releases.
### Technical preview
When a new feature is added to Kapacitor, it may be added in a "technical preview"
release for a few minor releases, and then later promoted to a fully supported v1 feature.
Technical preview features may be changed in backwards-incompatible ways until they are promoted to v1 features.
Technical previews allow new features to mature while maintaining regularly scheduled releases.
To make it clear which features of the API are in technical preview, the base path `/kapacitor/v1preview` is used.
If you wish to preview some of these new features, use the path `/kapacitor/v1preview` instead of `/kapacitor/v1` for your requests.
All v1 endpoints are available under the v1preview path so that your client does not need to be configured with multiple paths.
Technical preview endpoints are only available under the v1preview path.
{{% warn %}}
Using a technical preview means that you may have to update your client for
To get information about a task, make a `GET` request to the `/kapacitor/v1/tasks/TASK_ID` endpoint.
| Query Parameter | Default | Purpose |
| --------------- | ------- | ------- |
| dot-view | attributes | One of `labels` or `attributes`. Labels is less readable but will correctly render with all the information contained in labels. |
| script-format | formatted | One of `formatted` or `raw`. Raw will return the script identical to how it was defined. Formatted will first format the script. |
| replay-id | | Optional ID of a running replay. The returned task information will be in the context of the task for the running replay. |
A task has these read-only properties in addition to the properties listed [above](#defining-tasks).
| Property | Description |
| -------- | ----------- |
| dot | [GraphViz DOT](https://en.wikipedia.org/wiki/DOT_(graph_description_language)) syntax formatted representation of the task DAG. |
| executing | Whether the task is currently executing. |
| error | Any error encountered when executing the task. |
| stats | Map of statistics about a task. |
| created | Date the task was first created |
| modified | Date the task was last modified |
| last-enabled | Date the task was last set to status `enabled` |
To delete a task, make a DELETE request to the `/kapacitor/v1/tasks/TASK_ID` endpoint.
```
DELETE /kapacitor/v1/tasks/TASK_ID
```
#### Response
| Code | Meaning |
| ---- | ------- |
| 204 | Success |
{{% note %}}
**Note:** Deleting a non-existent task is not an error and will return a 204 success.
{{% /note %}}
### List tasks
To get information about several tasks, make a `GET` request to the `/kapacitor/v1/tasks` endpoint.
| Query Parameter | Default | Purpose |
| --------------- | ------- | ------- |
| pattern | | Filter results based on the pattern. Uses standard shell glob matching, see [this](https://golang.org/pkg/path/filepath/#Match) for more details. |
| fields | | List of fields to return. If empty returns all fields. Fields `id` and `link` are always returned. |
| dot-view | attributes | One of `labels` or `attributes`. Labels is less readable but will correctly render with all the information contained in labels. |
| script-format | formatted | One of `formatted` or `raw`. Raw will return the script identical to how it was defined. Formatted will first format the script. |
| offset | 0 | Offset count for paginating through tasks. |
| limit | 100 | Maximum number of tasks to return. |
To get information about a template, make a GET request to the `/kapacitor/v1/templates/TEMPLATE_ID` endpoint.
| Query Parameter | Default | Purpose |
| --------------- | ------- | ------- |
| script-format | formatted | One of `formatted` or `raw`. Raw will return the script identical to how it was defined. Formatted will first format the script. |
A template has these read only properties in addition to the properties listed [above](#defining-templates).
| Property | Description |
| -------- | ----------- |
| vars | Set of named vars from the TICKscript with their type, default values and description. |
| dot | [GraphViz DOT](https://en.wikipedia.org/wiki/DOT_(graph_description_language)) syntax formatted representation of the template DAG. NOTE: labels vs attributes does not matter since a template is never executing. |
To delete a template, make a DELETE request to the `/kapacitor/v1/templates/TEMPLATE_ID` endpoint.
{{% note %}}
**Note**:Deleting a template renders all associated tasks as orphans. The current state of the orphaned tasks will be left unmodified,
but orphaned tasks will not be able to be enabled.
{{% /note %}}
```
DELETE /kapacitor/v1/templates/TEMPLATE_ID
```
#### Response
| Code | Meaning |
| ---- | ------- |
| 204 | Success |
{{% note %}}
**Note**: Deleting a non-existent template is not an error and will return a 204 success.
{{% /note %}}
### List templates
To get information about several templates, make a GET request to the `/kapacitor/v1/templates` endpoint.
| Query Parameter | Default | Purpose |
| --------------- | ------- | ------- |
| pattern | | Filter results based on the pattern. Uses standard shell glob matching, see [this](https://golang.org/pkg/path/filepath/#Match) for more details. |
| fields | | List of fields to return. If empty returns all fields. Fields `id` and `link` are always returned. |
| script-format | formatted | One of `formatted` or `raw`. Raw will return the script identical to how it was defined. Formatted will first format the script. |
| offset | 0 | Offset count for paginating through templates. |
| limit | 100 | Maximum number of templates to return. |
In order to determine when a recording has finished you must make a GET request to the returned link typically something like `/kapacitor/v1/recordings/RECORDING_ID`.
A recording has these read only properties.
| Property | Description |
| -------- | ----------- |
| size | Size of the recording on disk in bytes. |
| date | Date the recording finished. |
| error | Any error encountered when creating the recording. |
| status | One of `recording` or `finished`. |
| progress | Number between 0 and 1 indicating the approximate progress of the recording. |
#### Example
```
GET /kapacitor/v1/recordings/e24db07d-1646-4bb3-a445-828f5049bea0
| 200 | Success, the recording is no longer running. |
| 202 | Success, the recording exists but is not finished. |
| 404 | No such recording exists. |
### Delete a recording
To delete a recording make a DELETE request to the `/kapacitor/v1/recordings/RECORDING_ID` endpoint.
```
DELETE /kapacitor/v1/recordings/RECORDING_ID
```
#### Response
| Code | Meaning |
| ---- | ------- |
| 204 | Success |
>NOTE: Deleting a non-existent recording is not an error and will return a 204 success.
### List recordings
To list all recordings, make a GET request to the `/kapacitor/v1/recordings` endpoint.
Recordings are sorted by date.
| Query Parameter | Default | Purpose |
| --------------- | ------- | ------- |
| pattern | | Filter results based on the pattern. Uses standard shell glob matching, see [this](https://golang.org/pkg/path/filepath/#Match) for more details. |
| fields | | List of fields to return. If empty returns all fields. Fields `id` and `link` are always returned. |
| offset | 0 | Offset count for paginating through tasks. |
| limit | 100 | Maximum number of tasks to return. |
- [Replay data without recording](#replay-data-without-recording)
- [Wait for replays](#wait-for-replays)
- [Delete a replay](#delete-a-replay)
- [List replays](#list-replays)
### Replay a recording
To replay a recording make a POST request to `/kapacitor/v1/replays/`
| Parameter | Default | Purpose |
| ---------- | ------- | ------- |
| id | random | Unique identifier for the replay. If empty a random ID is chosen. |
| task | | ID of task. |
| recording | | ID of recording. |
| 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. |
#### Example
Replay a recording using default parameters.
```
POST /kapacitor/v1/replays/
{
"task" : "TASK_ID",
"recording" : "RECORDING_ID"
}
```
Replay a recording in real-time mode and preserve recording times.
```
POST /kapacitor/v1/replays/
{
"task" : "TASK_ID",
"recording" : "RECORDING_ID",
"clock" : "real",
"recording-time" : true,
}
```
Replay a recording using a custom ID.
```
POST /kapacitor/v1/replays/
{
"id" : "MY_REPLAY_ID",
"task" : "TASK_ID",
"recording" : "RECORDING_ID"
}
```
#### Response
The request returns once the replay is started and provides a replay ID and link.
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. |
#### Example
Perform a replay using the `batch` method specifying a start time.
```
POST /kapacitor/v1/replays/batch
{
"task" : "TASK_ID",
"start" : "2006-01-02T15:04:05Z07:00"
}
```
Replay the results of the query against the task.
```
POST /kapacitor/v1/replays/query
{
"task" : "TASK_ID",
"query" : "SELECT mean(usage_idle) FROM cpu WHERE time > now() - 1h GROUP BY time(10m)",
}
```
Create a replay with a custom ID.
```
POST /kapacitor/v1/replays/query
{
"id" : "MY_REPLAY_ID",
"task" : "TASK_ID",
"query" : "SELECT mean(usage_idle) FROM cpu WHERE time > now() - 1h GROUP BY time(10m)",
}
```
#### Response
All replays are assigned an ID which is returned in this format with a link.
| 202 | Success, the replay exists but is not finished. |
| 404 | No such replay exists. |
### Delete a replay
To delete a replay make a DELETE request to the `/kapacitor/v1/replays/REPLAY_ID` endpoint.
```
DELETE /kapacitor/v1/replays/REPLAY_ID
```
#### Response
| Code | Meaning |
| ---- | ------- |
| 204 | Success |
{{% note %}}
**Note**: Deleting a non-existent replay is not an error and will return a 204 success.
{{% /note %}}
### List replays
You can list replays for a given recording by making a GET request to `/kapacitor/v1/replays`.
| Query Parameter | Default | Purpose |
| --------------- | ------- | ------- |
| pattern | | Filter results based on the pattern. Uses standard shell glob matching, see [this](https://golang.org/pkg/path/filepath/#Match) for more details. |
| fields | | List of fields to return. If empty returns all fields. Fields `id` and `link` are always returned. |
| offset | 0 | Offset count for paginating through tasks. |
| limit | 100 | Maximum number of tasks to return. |
The API allows you to see the current state of any alert and to configure various handlers for the alerts.
- [Topics](#topics)
- [Create and remove topics](#create-and-remove-topics)
- [List topics](#list-topics)
- [Topic state](#topic-state)
- [List topic events](#list-topic-events)
- [Topic events](#topic-events)
- [List topic handlers](#list-topic-handlers)
- [Get a topic handler](#get-a-topic-handler)
- [Create a topic handler](#create-a-topic-handler)
- [Update a topic handler](#update-a-topic-handler)
- [Remove a topic handler](#remove-a-topic-handler)
### Topics
Alerts are grouped into topics.
An alert handler "listens" on a topic for any new events.
You can either specify the alert topic in the TICKscript or one will be generated for you.
### Create and remove topics
Topics are created dynamically when they referenced in TICKscripts or in handlers.
To delete a topic make a `DELETE` request to `/kapacitor/v1/alerts/topics/<topic id>`.
This will delete all known events and state for the topic.
{{% note %}}
**Note**: Since topics are dynamically created, a topic may return after having deleted it, if a new event is created for the topic.
{{% /note %}}
#### Example
```
DELETE /kapacitor/v1/alerts/topics/system
```
### List topics
To query the list of available topics make a GET requests to `/kapacitor/v1/alerts/topics`.
| Query Parameter | Default | Purpose |
| --------------- | ------- | ------- |
| min-level | OK | Only return topics that are greater or equal to the min-level. Valid values include OK, INFO, WARNING, CRITICAL. |
| pattern | * | Filter results based on the pattern. Uses standard shell glob matching on the topic ID, see [this](https://golang.org/pkg/path/filepath/#Match) for more details. |
You can get a list of handlers configured for a topic by making a GET request to `/kapacitor/v1/alerts/topics/<topic id>/handlers`.
| Query Parameter | Default | Purpose |
| --------------- | ------- | ------- |
| pattern | * | Filter results based on the pattern. Uses standard shell glob matching on the service name, see [this](https://golang.org/pkg/path/filepath/#Match) for more details. |
{{% note %}}
**Note**: Anonymous handlers (created automatically from TICKscripts) will not be listed under their associated anonymous topic as they are not configured via the API.
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.
### Recover from bad configurations
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 startup.
{{% note %}}
**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.
{{% /note %}}
### Overview
The paths for the configuration API endpoints are as follows:
A list of services that can be tested is available at the `/kapacitor/v1/service-tests` endpoint
| Query Parameter | Default | Purpose |
| --------------- | ------- | ------- |
| pattern | * | Filter results based on the pattern. Uses standard shell glob matching on the service name, see [this](https://golang.org/pkg/path/filepath/#Match) for more details. |
You can 'ping' the Kapacitor server to validate you have a successful connection.
A ping request does nothing but respond with a 204.
{{% note %}}
**Note**: The Kapacitor server version is returned in the `X-Kapacitor-Version` HTTP header on all requests.
Ping is a useful request if you simply need the verify the version of server you are talking to.
{{% /note %}}
#### Example
```
GET /kapacitor/v1/ping
```
Response:
```
| Code | Meaning |
| ---- | ------- |
| 204 | Success |
```
### Reload sideload
You can trigger a reload of all sideload sources by making an HTTP POST request to `kapacitor/v1/sideload/reload`, with an empty body.
#### Example
```
POST /kapacitor/v1/sideload/reload
```
Response:
```
| Code | Meaning |
| ---- | ------- |
| 204 | Success |
```
### /debug/vars HTTP endpoint
Kapacitor exposes statistics and information about its runtime through the `/debug/vars` endpoint, which can be accessed using the following cURL command:
Server statistics and information are displayed in JSON format.
{{% note %}}
**Note:** You can use the [Telegraf Kapacitor input plugin](https://github.com/influxdata/telegraf/tree/release-1.7/plugins/inputs/kapacitor) to collect metrics (using the `/debug/vars` endpoint) from specified Kapacitor instances. For a list of the measurements and fields, see the plugin README.
{{% /note %}}
### /debug/pprof HTTP endpoints
Kapacitor supports the Go [net/http/pprof](https://golang.org/pkg/net/http/pprof/) endpoints, which can be useful for troubleshooting. The `pprof` package serves runtime profiling data in the format expected by the _pprof_ visualization tool.
The `/debug/pprof/` endpoint generates an HTML page with a list of built-in Go profiles and hyperlinks for each.
| Profile | Description
| :---------------- | :-------------------- |
| block | Stack traces that led to blocking on synchronization primitives. |
| goroutine | Stack traces of all current goroutines. |
| heap | Sampling of stack traces for heap allocations. |
| mutex | Stack traces of holders of contended mutexes. |
| threadcreate | Stack traces that led to the creation of new OS threads. |
To access one of the the `/debug/pprof/` profiles listed above, use the following cURL request, substituting `<profile>` with the name of the profile. The resulting profile is output to a file, specified for `<path/to/output-file>`.
