Skip to main content
API docs by Redocly

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 the tenzir-ctl web generate-token command.

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 start_when_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.

start_when_created
boolean
Default: false

Start this pipeline upon creation. This parameter must be true if the hidden parameter is also true.

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.

restart_with_node
boolean
Default: false

Check if the pipeline should be restarted when the Tenzir Node is restarted. This parameter must be false if the hidden parameter is true.

Responses

Request samples

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

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": 7
}

Response samples

Content type
application/json
{ }

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.

restart_with_node
boolean

Flag that specifies whether the pipeline should be restarted when the Tenzir Node is restarted.

Responses

Request samples

Content type
application/json
{
  • "id": 7,
  • "action": "start",
  • "name": "zeek-monitoring-pipeline",
  • "restart_with_node": true
}

Response samples

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

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.

start_when_created
boolean
Default: false

Start this pipeline upon creation. This parameter must be true if the hidden parameter is also true.

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.

restart_with_node
boolean
Default: false

Check if the pipeline should be restarted when the Tenzir Node is restarted. This parameter must be false if the hidden parameter is true.

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",
  • "start_when_created": false,
  • "name": "zeek-monitoring-pipeline",
  • "hidden": false,
  • "ttl": "5.0m",
  • "restart_with_node": false,
  • "serve_id": "4ada2434-32asfe2s",
  • "serve_buffer_size": 4000
}

Response samples

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

Return data from a pipeline

Returns events from an existing pipeline. The pipeline definition must include a serve operator.

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

The maximum number of events returned. If unset, the number is unlimited.

timeout
string
Default: "100.0ms"

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.

Responses

Request samples

Content type
application/json
{
  • "serve_id": "query1",
  • "continuation_token": "340ce2j",
  • "max_events": 50,
  • "timeout": "100.0ms"
}

Response samples

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

Return current status

Returns the current status of the whole node.

Authorizations:
TenzirToken
Request Body schema: application/json

Body for the status endpoint

component
string

If specified, return the status for that component only.

verbosity
string
Default: "info"
Enum: "info" "detailed" "debug"

Responses

Request samples

Content type
application/json
{
  • "component": "index",
  • "verbosity": "info"
}

Response samples

Content type
application/json
{
  • "catalog": {
    },
  • "version": {
    }
}