Tenzir REST API ("v0")

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.

All endpoints are versioned, and must be prefixed with /v0.

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

id	string The id of the pipeline to be updated. If not provided, a random id will be generated.
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 start automatically, 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: "1min" 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.
unstoppable	boolean Default: false A flag specifying whether this pipeline is unstoppable. Unstoppable pipelines start automatically, fail when they complete, and can not be paused or stopped manually.

Responses

Request samples

Payload

Content type

application/json

{"id": "08446737-da9b-4787-8599-97d85c48c3bb",
"definition": "export | where foo | publish /bar",
"name": "zeek-monitoring-pipeline",
"hidden": false,
"ttl": "5min",
"autostart": {"created": true,
"completed": false,
"failed": false
},
"autodelete": {"completed": false,
"failed": true,
"stopped": false
},
"retry_delay": "500ms",
"unstoppable": true
}

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

required

string

The id of the pipeline to be deleted.

Responses

Request samples

Payload

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

id	string The id of the pipeline to be updated. If not provided, a random id will be generated.
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 start automatically, 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: "1min" 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.
unstoppable	boolean Default: false A flag specifying whether this pipeline is unstoppable. Unstoppable pipelines start automatically, fail when they complete, and can not be paused or stopped manually.
cache_id	string The identifier for the `cache` operator, which is inserted only when this parameter is provided.
cache_capacity	integer The maximum number of events to keep in the `cache` operator.
cache_read_timeout	string The time to live of the cache. Resets when reading from the cache.
cache_write_timeout	string The maximum time to live of the cache. Unlike the `cache_read_timeout` parameter, this does not reset when reading from the cache.
serve_id	string The identifier for the `serve` operator.
serve_buffer_size	integer The maximum number of events to keep in the `serve` operator.

Responses

Request samples

Payload

Content type

application/json

{"id": "08446737-da9b-4787-8599-97d85c48c3bb",
"definition": "export | where foo | publish /bar",
"name": "zeek-monitoring-pipeline",
"hidden": false,
"ttl": "5min",
"autostart": {"created": true,
"completed": false,
"failed": false
},
"autodelete": {"completed": false,
"failed": true,
"stopped": false
},
"retry_delay": "500ms",
"unstoppable": true,
"cache_id": "4ada2434-32asfe2s",
"cache_capacity": 4000,
"cache_read_timeout": "1min",
"cache_write_timeout": "1h",
"serve_id": "4ada2434-32asfe2s",
"serve_buffer_size": 4000
}

Response samples

Content type

application/json

Example

Launch Response For Pipeline With Explicit Sink

{"deployable": true
}

List all existing pipelines

Lists all existing pipelines.

Authorizations:

TenzirToken

Responses

Response samples

Content type

application/json

{"pipelines": [{"id": "4c7f2b11-6169-4d1b-89b4-4fc0a68b3d4a",
"name": "user-assigned-name",
"definition": "export | where foo | publish /bar",
"hidden": false,
"created_at": 1706180157837037600,
"last_modifed": 1706180157837038000,
"state": "running",
"error": null,
"diagnostics": [ ]
},
{"id": "08446737-da9b-4787-8599-97d85c48c3bb",
"name": "wrong-pipeline",
"definition": "export asdf",
"hidden": false,
"created_at": 1706180157837037600,
"last_modifed": 1706180157837038000,
"state": "failed",
"error": "format 'asdf' not found",
"diagnostics": [ ]
}
]
}

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

Payload

Content type

application/json

{"ids": [7,
1,
3
]
}

Response samples

Content type

application/json

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

TenzirToken

Request Body schema: application/json

Body for the update endpoint

id required	string The id of the pipeline to be updated.
definition	string The updated definition of the pipeline.
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.
unstoppable	boolean A flag specifying whether this pipeline is unstoppable. Unstoppable pipelines start automatically, fail when they complete, and can not be paused or stopped manually.

Responses

Request samples

Payload

Content type

application/json

{"id": "08446737-da9b-4787-8599-97d85c48c3bb",
"definition": "export | where baz | publish /foo",
"action": "start",
"name": "zeek-monitoring-pipeline",
"labels": [{"text": "zeek",
"color": "3F1A24"
}
],
"autostart": {"created": true,
"completed": false,
"failed": false
},
"autodelete": {"completed": false,
"failed": true,
"stopped": false
},
"retry_delay": "500ms",
"unstoppable": true
}

Response samples

Content type

application/json

{"pipeline": {"id": "string",
"name": "string",
"definition": "string",
"unstoppable": true,
"hidden": null,
"created_at": 0,
"last_modified": 0,
"start_time": "string",
"total_runs": 0,
"state": "created",
"error": "string",
"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"
}
],
"labels": [{"text": "zeek",
"color": "3F1A24"
}
],
"retry_delay": "10s",
"autostart": {"created": true,
"completed": false,
"failed": false
},
"autodelete": {"completed": false,
"failed": true,
"stopped": false
},
"ttl": "2min",
"remaining_ttl": "10s"
}
}

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: 5s) 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: "5s" The maximum amount of time spent on the request. Hitting the timeout is not an error. The timeout must not be greater than 10 seconds.
schema	string Default: "legacy" The output format in which schemas are represented. Must be one of "legacy", "exact", or "never". Use "exact" to switch to a type representation matching Tenzir's type system exactly, and "never" to omit schema schema definitions from the output entirely.

Responses

Request samples

Payload

Content type

application/json

{"serve_id": "query1",
"continuation_token": "340ce2j",
"max_events": 1024,
"min_events": 1,
"timeout": "200ms",
"schema": "exact"
}

Response samples

Content type

application/json

{"next_continuation_token": "340ce2j",
"state": "running",
"schemas": [{"schema_id": "c631d301e4b18f4",
"definition": [{"name": "tenzir.summarize",
"kind": "record",
"type": "tenzir.summarize",
"attributes": { },
"path": [ ],
"fields": [{"name": "severity",
"kind": "string",
"type": "string",
"attributes": { },
"path": [0
],
"fields": [ ]
},
{"name": "pipeline_id",
"kind": "string",
"type": "string",
"attributes": { },
"path": [1
],
"fields": [ ]
}
]
}
]
}
],
"events": [{"schema_id": "c631d301e4b18f4",
"data": {"timestamp": "2023-04-26T12:00:00Z",
"schema": "zeek.conn",
"schema_id": "ab2371bas235f1",
"events": 50
}
},
{"schema_id": "c631d301e4b18f4",
"data": {"timestamp": "2023-04-26T12:05:00Z",
"schema": "suricata.dns",
"schema_id": "cd4771bas235f1",
"events": 50
}
}
]
}