Skip to content

Launch a new pipeline

POST
/pipeline/launch
 
curl --request POST \
  --url https://example.com/api/v0/pipeline/launch \
  --header 'Content-Type: application/json' \
  --header 'X-Tenzir-Token: <X-Tenzir-Token>' \
  --data '{ "definition": "export | where foo", "name": "interactive-query", "serve_id": "query-1", "serve_buffer_size": 4000 }'

Creates a pipeline and prepares it for interactive use. If the pipeline does not end with a sink, Tenzir adds an implicit output stream and returns the created pipeline ID. If the pipeline already has a sink, Tenzir returns deployable: true so the caller can deploy it explicitly.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Pipeline launch request.

Media type application/json
object
id

The pipeline ID. If omitted, Tenzir generates a random ID.

string
definition
required

The pipeline definition.

string
name

The human-readable name of the pipeline.

string
default: [an auto-generated id]
hidden

Whether this pipeline is hidden.

boolean
ttl

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 finite and defined if the hidden parameter is true.

string
nullable
autostart

Flags that specify on which state to restart the pipeline.

object
created

Autostart the pipeline upon creation.

boolean
completed

Autostart the pipeline upon completion.

boolean
failed

Autostart the pipeline upon failure.

boolean
autodelete

Flags that specify on which state to delete the pipeline.

object
completed

Autodelete the pipeline upon completion.

boolean
failed

Autodelete the pipeline upon failure.

boolean
stopped

Autodelete the pipeline when it stops before completing.

boolean
retry_delay

The minimum time between automatic restarts after a pipeline error.

string
default: 1min
unstoppable

Whether this pipeline is unstoppable.

boolean
cache_id

The identifier for the cache operator, which is inserted only when this parameter is provided.

string
cache_capacity

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

integer
>= 1
cache_read_timeout

The time to live of the cache. Resets when reading from the cache.

string
cache_write_timeout

The maximum time to live of the cache. Unlike the cache_read_timeout parameter, this does not reset when reading from the cache.

string
serve_id

The output stream identifier to create for reading events from this pipeline.

string
serve_buffer_size

The maximum number of events to buffer for the output stream.

integer
>= 1
Example 
{
  "definition": "export | where foo",
  "name": "interactive-query",
  "serve_id": "query-1",
  "serve_buffer_size": 4000
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The launch request was accepted.

Media type application/json
One of:
object
deployable

Returns this property with the value true.

boolean
Example 
{
  "deployable": true
}

400

Section titled “400 ”

Invalid arguments or invalid pipeline.

Media type application/json
object
error
required

The error message.

string
diagnostics
Array<object>
object
severity
string
Allowed values: error warning note
message
string
annotation
Array<object>
object
primary
boolean
text

A potentially empty label.

string
source

A region in the source code, defined by byte offsets.

object
begin
number
end
number
notes
Array<object>
object
kind
string
Allowed values: note usage hint docs
message
string
rendered
string
Example 
{
  "error": "Invalid arguments",
  "diagnostics": [
    {
      "severity": "error",
      "message": "unknown option `--frobnify`",
      "annotation": [
        {
          "text": "this option does not exist",
          "source": {
            "begin": 42,
            "end": 48
          }
        }
      ],
      "notes": [
        {
          "kind": "note",
          "message": "file <path> [-f|--follow] [-m|--mmap] [-t|--timeout <duration>]"
        }
      ],
      "rendered": "\u001b[1m\u001b[31merror\u001b[39m: unknown option `--frobnify`\u001b[0m\n"
    }
  ]
}