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.
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:
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 |
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 |
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 |
Responses
Request samples
- Payload
{- "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
- 200
- 400
{- "id": "string"
}
Delete an existing pipeline
Deletes an existing pipeline.
Authorizations:
Request Body schema: application/json
Body for the delete endpoint
id required | string The id of the pipeline to be deleted. |
Responses
Request samples
- Payload
{- "id": 7
}
Response samples
- 200
- 400
{ }
Response samples
- 200
- 400
{- "pipelines": [
- {
- "id": "string",
- "name": "string",
- "definition": "string",
- "state": "created",
- "error": "string",
- "restart_with_node": false,
- "operators": [
- {
- "id": "string",
- "definition": "string",
- "instrumented": true
}
], - "diagnostics": [
- {
- "severity": "error",
- "message": "unknown option `--frobnify`",
- "annotation": [
- {
- "primary": true,
- "text": "this option does not exist",
- "source": {
- "begin": 42,
- "end": 48
}
}
], - "notes": [
- {
- "kind": "usage",
- "message": "file <path> [-f|--follow] [-m|--mmap] [-t|--timeout <duration>]"
}
], - "rendered": "\u001b[1m\u001b[31merror\u001b[39m: unknown option `--frobnify`\u001b[0m\n"
}
], - "metrics": {
- "total": {
- "ingress": {
- "unit": "bytes"
}, - "egress": {
- "unit": "bytes"
}
}
}
}
]
}
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:
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
- Payload
{- "ids": [
- 7,
- 1,
- 3
]
}
Response samples
- 200
- 400
{- "ids": [
- 7,
- 1
]
}
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:
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
- Payload
{- "id": 7,
- "action": "start",
- "name": "zeek-monitoring-pipeline",
- "restart_with_node": true
}
Response samples
- 200
- 400
{- "pipeline": {
- "id": "string",
- "name": "string",
- "definition": "string",
- "state": "created",
- "error": "string",
- "restart_with_node": false,
- "operators": [
- {
- "id": "string",
- "definition": "string",
- "instrumented": true
}
], - "diagnostics": [
- {
- "severity": "error",
- "message": "unknown option `--frobnify`",
- "annotation": [
- {
- "primary": true,
- "text": "this option does not exist",
- "source": {
- "begin": 42,
- "end": 48
}
}
], - "notes": [
- {
- "kind": "usage",
- "message": "file <path> [-f|--follow] [-m|--mmap] [-t|--timeout <duration>]"
}
], - "rendered": "\u001b[1m\u001b[31merror\u001b[39m: unknown option `--frobnify`\u001b[0m\n"
}
], - "metrics": {
- "total": {
- "ingress": {
- "unit": "bytes"
}, - "egress": {
- "unit": "bytes"
}
}
}
}
}
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:
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 |
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 |
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 |
serve_id required | string The identifier for the |
serve_buffer_size | integer The maximum number of events to keep in the |
Responses
Request samples
- Payload
{- "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
- 200
- 400
{- "id": "string",
- "deployable": true
}
Return data from a pipeline
Returns events from an existing pipeline. The pipeline definition must include a serve operator.
Authorizations:
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
- Payload
{- "serve_id": "query1",
- "continuation_token": "340ce2j",
- "max_events": 50,
- "timeout": "100.0ms"
}
Response samples
- 200
- 400
{- "next_continuation_token": "340ce2j",
- "dropped": 0,
- "schemas": [
- {
- "schema_id": "c631d301e4b18f4",
- "definition": {
- "record": [
- {
- "timestamp": "time",
- "schema": "string",
- "schema_id": "string",
- "events": "uint64"
}
]
}
}
], - "data": [
- {
- "schema_id": "c631d301e4b18f4",
- "data": {
- "timestamp": "2023-04-26T12:00:00.000000",
- "schema": "zeek.conn",
- "schema_id": "ab2371bas235f1",
- "events": 50
}
}, - {
- "schema_id": "c631d301e4b18f4",
- "data": {
- "timestamp": "2023-04-26T12:05:00.000000",
- "schema": "suricata.dns",
- "schema_id": "cd4771bas235f1",
- "events": 50
}
}
]
}
Return current status
Returns the current status of the whole node.
Authorizations:
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
- Payload
{- "component": "index",
- "verbosity": "info"
}
Response samples
- 200
{- "catalog": {
- "num-partitions": 7092,
- "memory-usage": 52781901584
}, - "version": {
- "Tenzir": "v2.3.0-rc3-32-g8529a6c43f"
}
}