Skip to content

Update pipeline state

POST
/pipeline/update
 
curl --request POST \
  --url https://example.com/api/v0/pipeline/update \
  --header 'Content-Type: application/json' \
  --header 'X-Tenzir-Token: <X-Tenzir-Token>' \
  --data '{ "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": false, "completed": false, "failed": false }, "autodelete": { "completed": false, "failed": false, "stopped": false }, "retry_delay": "500ms", "unstoppable": true }'

Updates the definition, metadata, or lifecycle state of a pipeline. Tenzir leaves omitted fields unchanged.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Body for the update endpoint

Media type application/json
object
id
required

The id of the pipeline to be updated.

string
Example 
08446737-da9b-4787-8599-97d85c48c3bb
definition

The updated definition of the pipeline.

string
Example 
export | where baz | publish /foo
action

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

string
Allowed values: start pause stop
Example 
start
name

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

string
Example 
zeek-monitoring-pipeline
labels

The user-provided labels for this pipeline.

Array<object>
object
text

The pipeline label text.

string
Example 
zeek
color

The pipeline label color.

string
Example 
3F1A24
autostart

Flags that specify on which state to restart the pipeline.

object
created

Autostart the pipeline upon creation.

boolean
Example 
true
completed

Autostart the pipeline upon completion.

boolean
Example 
false
failed

Autostart the pipeline upon failure.

boolean
Example 
false
autodelete

Flags that specify on which state to delete the pipeline.

object
completed

Autodelete the pipeline upon completion.

boolean
Example 
false
failed

Autodelete the pipeline upon failure.

boolean
Example 
true
stopped

Autodelete the pipeline when it stops before completing.

boolean
Example 
false
retry_delay

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.

string
Example 
500ms
unstoppable

A flag specifying whether this pipeline is unstoppable. Unstoppable pipelines start automatically, fail when they complete, and can not be paused or stopped manually.

boolean
Example 
true

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The pipeline was updated.

Media type application/json

The updated pipeline.

object
pipeline
object
id

The pipeline id.

string
name

The human-readable name of the pipeline.

string
definition

The pipeline definition.

string
unstoppable

A flag specifying whether this pipeline is unstoppable. Unstoppable pipelines start automatically, fail when they complete, and can not be paused or stopped manually.

boolean
hidden

Whether this pipeline is hidden. Hidden pipelines are only available through the show pipelines operator.

boolean
created_at

The Unix timestamp of the pipeline creation time in nanoseconds.

integer format: int64
last_modified

The Unix timestamp of the last pipeline modification in nanoseconds.

integer format: int64
start_time

If the pipeline has been started, the ISO 8601 timestamp of the most recent start.

string
total_runs

The total amount of runs this pipeline has attempted so far.

integer
state
string
Allowed values: created running paused failed stopped completed
error

The error that the pipeline may have encountered during running.

string
nullable
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
labels

The user-provided labels for this pipeline.

Array<object>
object
text

The pipeline label text.

string
color

The pipeline label color.

string
retry_delay

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.

string
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
ttl

If a TTL exists for this pipeline, the TTL as a duration string.

string
nullable
remaining_ttl

If a TTL exists for this pipeline, the remaining TTL as a duration string.

string
nullable
Example 
{
  "pipeline": {
    "unstoppable": true,
    "state": "created",
    "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"
      }
    ],
    "labels": [
      {
        "text": "zeek",
        "color": "3F1A24"
      }
    ],
    "retry_delay": "10s",
    "autostart": {
      "created": false,
      "completed": false,
      "failed": false
    },
    "autodelete": {
      "completed": false,
      "failed": false,
      "stopped": false
    },
    "ttl": "2min",
    "remaining_ttl": "10s"
  }
}

400

Section titled “400 ”

Invalid arguments.

Media type application/json
object
error
required

The error message.

string
Example 
{
  "error": "Invalid arguments"
}