elasticsearch/docs/reference/rest-api/logstash/put-pipeline.asciidoc

[role="xpack"]
[[logstash-api-put-pipeline]]
=== Create or update {ls} pipeline API
++++
<titleabbrev>Create or update {ls} pipeline</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-logstash[{ls} APIs].
--

This API creates or updates a {ls} pipeline used for
{logstash-ref}/logstash-centralized-pipeline-management.html[{ls} Central
Management].

[[logstash-api-put-pipeline-request]]
==== {api-request-title}

`PUT _logstash/pipeline/<pipeline_id>`

[[logstash-api-put-pipeline-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the
`manage_logstash_pipelines` cluster privilege to use this API.

[[logstash-api-put-pipeline-desc]]
==== {api-description-title}

Creates a {ls} pipeline. If the specified pipeline exists, the pipeline is
replaced.

[[logstash-api-put-pipeline-params]]
==== {api-path-parms-title}

`<pipeline_id>`::
  (Required, string) Identifier for the pipeline.

[[logstash-api-put-pipeline-request-body]]
==== {api-request-body-title}

`description`::
(Optional, string)
Description of the pipeline. This description is not used by {es} or {ls}.

`last_modified`::
(Required, string)
Date the pipeline was last updated. Must be in the `yyyy-MM-dd'T'HH:mm:ss.SSSZZ`
<<mapping-date-format,`strict_date_time`>> format.

`pipeline`::
(Required, string)
Configuration for the pipeline. For supported syntax, see the
{logstash-ref}/configuration-file-structure.html[{ls} configuration
documentation].

`pipeline_metadata`::
(Required, object)
Optional metadata about the pipeline. May have any contents. This metadata is
not generated or used by {es} or {ls}.

`pipeline_settings`::
(Required, object)
Settings for the pipeline. Supports only flat keys in dot notation. For
supported settings, see the {logstash-ref}/logstash-settings-file.html[{ls}
settings documentation].

`username`::
(Required, string)
User who last updated the pipeline.

[[logstash-api-put-pipeline-example]]
==== {api-examples-title}

The following example creates a new pipeline named `my_pipeline`:

[source,console]
--------------------------------------------------
PUT _logstash/pipeline/my_pipeline
{
  "description": "Sample pipeline for illustration purposes",
  "last_modified": "2021-01-02T02:50:51.250Z",
  "pipeline_metadata": {
    "type": "logstash_pipeline",
    "version": "1"
  },
  "username": "elastic",
  "pipeline": "input {}\n filter { grok {} }\n output {}",
  "pipeline_settings": {
    "pipeline.workers": 1,
    "pipeline.batch.size": 125,
    "pipeline.batch.delay": 50,
    "queue.type": "memory",
    "queue.max_bytes": "1gb",
    "queue.checkpoint.writes": 1024
  }
}
--------------------------------------------------

If the request succeeds, you receive an empty response with an appropriate
status code.