Skip to main content

Tenzir REST API ("0.1")

Download OpenAPI specification:Download

This API can be used to interact with a Tenzir Node in a RESTful manner.

All API requests must be authenticated with a valid token, which must be supplied in the X-Tenzir-Token request header. The token can be generated on the command-line using tenzir-ctl web generate-token.

Returns a success response

Returns a success response to indicate that the node is able to respond to requests. The response body includes the current node version.

Authorizations:
TenzirToken

Responses

Response samples

Content type
application/json
{
  • "version": "v2.3.0-rc3-32-g8529a6c43f"
}

Create a new pipeline

Creates a new pipeline. If autostart.created is true, the response is only sent after the pipeline was successfully started. If this fails, then the pipeline is immediately discarded, and the response contains the observed diagnostics. The error field then contains a rendered representation of the diagnostics. Otherwise, the diagnostics field is not present.

Authorizations:
TenzirToken
Request Body schema: application/json
definition
required
string

The pipeline definition.

name
string
Default: "[an auto-generated id]"

The human-readable name of the pipeline.

hidden
boolean
Default: false

A flag specifying whether this pipeline is hidden. Hidden pipelines are not persisted and will not show up in the /pipeline/list endpoint response.

ttl
string
Default: null

A duration string specifying the maximum time for this pipeline to exist. No value means the pipeline is allowed to exist forever. This parameter must be defined if the hidden parameter is true.

object (PipelineAutostart)

Flags that specify on which state to restart the pipeline.

object (PipelineAutodelete)

Flags that specify on which state to delete the pipeline.

retry_delay
string
Default: "1.0m"

A duration string specifying the minimum time between automatic restarts of a pipeline when an error occurs. Takes no effect if restarting on failure is disabled.

Responses

Request samples

Content type
application/json
{
  • "definition": "export | where foo | publish /bar",
  • "name": "zeek-monitoring-pipeline",
  • "hidden": false,
  • "ttl": "5.0m",
  • "autostart": {
    },
  • "autodelete": {
    },
  • "retry_delay": "500.0ms"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Delete an existing pipeline

Deletes an existing pipeline.

Authorizations:
TenzirToken
Request Body schema: application/json

Body for the delete endpoint

id
required
string

The id of the pipeline to be deleted.

Responses

Request samples

Content type
application/json
{
  • "id": "4c7f2b11-6169-4d1b-89b4-4fc0a68b3d4a"
}

Response samples

Content type
application/json
{ }

Launch a new pipeline

Depending on whether the pipeline ends with a sink, create the pipeline with a serve sink with the provided /pipeline/create parameters or notify that this pipeline is deployable for further action.

Authorizations:
TenzirToken
Request Body schema: application/json
definition
required
string

The pipeline definition.

name
string
Default: "[an auto-generated id]"

The human-readable name of the pipeline.

hidden
boolean
Default: false

A flag specifying whether this pipeline is hidden. Hidden pipelines are not persisted and will not show up in the /pipeline/list endpoint response.

ttl
string
Default: null

A duration string specifying the maximum time for this pipeline to exist. No value means the pipeline is allowed to exist forever. This parameter must be defined if the hidden parameter is true.

object (PipelineAutostart)

Flags that specify on which state to restart the pipeline.

object (PipelineAutodelete)

Flags that specify on which state to delete the pipeline.

retry_delay
string
Default: "1.0m"

A duration string specifying the minimum time between automatic restarts of a pipeline when an error occurs. Takes no effect if restarting on failure is disabled.

serve_id
required
string

The identifier for the server operator.

serve_buffer_size
integer

The maximum number of events to keep in the serve operator.

Responses

Request samples

Content type
application/json
{
  • "definition": "export | where foo | publish /bar",
  • "name": "zeek-monitoring-pipeline",
  • "hidden": false,
  • "ttl": "5.0m",
  • "autostart": {
    },
  • "autodelete": {
    },
  • "retry_delay": "500.0ms",
  • "serve_id": "4ada2434-32asfe2s",
  • "serve_buffer_size": 4000
}

Response samples

Content type
application/json
Example
{
  • "deployable": true
}

List all existing pipelines

Lists all existing pipelines.

Authorizations:
TenzirToken

Responses

Response samples

Content type
application/json
{
  • "pipelines": [
    ]
}

Reset the TTL of an existing pipeline

Resets the TTL of an existing pipeline as specified, if one has been specified in the /create endpoint before. Resetting the TTL means that the TTL-related timeout will start counting from zero seconds again, thus keeping the pipeline alive for longer.

Authorizations:
TenzirToken
Request Body schema: application/json

Body for the reset-ttl endpoint

ids
required
Array of strings

The id of pipelines whose TTL should be updated.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ids": [
    ]
}

Update pipeline state

Update the state of the pipeline. All values that are not explicitly included in the request are left in their old state.

Authorizations:
TenzirToken
Request Body schema: application/json

Body for the update endpoint

id
required
string

The id of the pipeline to be updated.

action
string
Enum: "start" "pause" "stop"

The action that will change the pipeline's running state.

name
string

Update the human-readable name of the pipeline to this value.

Array of objects (PipelineLabels)

The user-provided labels for this pipeline.

object (PipelineAutostart)

Flags that specify on which state to restart the pipeline.

object (PipelineAutodelete)

Flags that specify on which state to delete the pipeline.

retry_delay
string

A duration string specifying the minimum time between automatic restarts of a pipeline when an error occurs. Takes no effect if restarting on failure is disabled.

Responses

Request samples

Content type
application/json
{
  • "id": "08446737-da9b-4787-8599-97d85c48c3bb",
  • "action": "start",
  • "name": "zeek-monitoring-pipeline",
  • "labels": [
    ],
  • "autostart": {
    },
  • "autodelete": {
    },
  • "retry_delay": "500.0ms"
}

Response samples

Content type
application/json
{
  • "pipeline": {
    }
}

Return data from a pipeline

Returns events from an existing pipeline. The pipeline definition must include a serve operator. By default, the endpoint performs long polling (timeout: 2s) and returns events as soon as they are available (min_events: 1).

Authorizations:
TenzirToken
Request Body schema: application/json

Body for the serve endpoint

serve_id
required
string

The id that was passed to the serve operator.

continuation_token
string

The continuation token that was returned with the last response. For the initial request this is null.

max_events
integer
Default: 1024

The maximum number of events returned.

min_events
integer
Default: 1

Wait for this number of events before returning.

timeout
string
Default: "2.0s"

The maximum amount of time spent on the request. Hitting the timeout is not an error. The timeout must not be greater than 5 seconds.

use_simple_format
bool
Default: false

Use an experimental, more simple format for the contained schema, and render durations as numbers representing seconds as opposed to human-readable strings.

Responses

Request samples

Content type
application/json
{
  • "serve_id": "query1",
  • "continuation_token": "340ce2j",
  • "max_events": 1024,
  • "min_events": 1,
  • "timeout": "2.0s",
  • "use_simple_format": true
}

Response samples

Content type
application/json
{
  • "next_continuation_token": "340ce2j",
  • "schemas": [
    ],
  • "events": [
    ]
}