[[put-pipeline-api]]
=== Create or update pipeline API
++++
<titleabbrev>Create or update pipeline</titleabbrev>
++++

Creates or updates an <<ingest,ingest pipeline>>. Changes made using this API
take effect immediately.

[source,console]
----
PUT _ingest/pipeline/my-pipeline-id
{
  "description" : "My optional pipeline description",
  "processors" : [
    {
      "set" : {
        "description" : "My optional processor description",
        "field": "my-keyword-field",
        "value": "foo"
      }
    }
  ]
}
----


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

`PUT /_ingest/pipeline/<pipeline>`

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

* If the {es} {security-features} are enabled, you must have the
`manage_pipeline`, `manage_ingest_pipelines`, or `manage`
<<privileges-list-cluster,cluster privilege>> to use this API.


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

`<pipeline>`::
(Required, string) ID of the ingest pipeline to create or update.
+
[IMPORTANT]
====
To avoid naming collisions with built-in and Fleet-managed ingest pipelines, avoid using `@` as part of your own ingest pipelines names.
The exception of that rule are the `*@custom` ingest pipelines that let you safely add a custom pipeline to managed pipelines.
See also <<pipelines-for-fleet-elastic-agent>>.
====

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

`if_version`::
(Optional, integer) Perform the operation only if the pipeline has this
version. If specified and the update is successful, the pipeline's
version is incremented.

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]

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

// tag::pipeline-object[]
`description`::
(Optional, string)
Description of the ingest pipeline.

`on_failure`::
(Optional, array of <<processors,processor>> objects)
Processors to run immediately after a processor failure.
+
Each processor supports a processor-level `on_failure` value. If a processor
without an `on_failure` value fails, {es} uses this pipeline-level parameter as
a fallback. The processors in this parameter run sequentially in the order
specified. {es} will not attempt to run the pipeline's remaining processors.

`processors`::
(Required, array of <<processors,processor>> objects)
Processors used to perform transformations on documents before indexing.
Processors run sequentially in the order specified.

`version`::
(Optional, integer)
Version number used by external systems to track ingest pipelines.
+
See the <<put-pipeline-api-query-params,`if_version`>> parameter above for
how the version attribute is used.

`_meta`::
(Optional, object)
Optional metadata about the ingest pipeline. May have any contents. This
map is not automatically generated by {es}.

`deprecated`::
(Optional, boolean)
Marks this ingest pipeline as deprecated.
When a deprecated ingest pipeline is referenced as the default or final pipeline when creating or updating a non-deprecated index template,
{es} will emit a deprecation warning.
// end::pipeline-object[]

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

[[pipeline-metadata]]
===== Pipeline metadata

You can use the `_meta` parameter to add arbitrary metadata to a pipeline.
This user-defined object is stored in the cluster state,
so keeping it short is preferable.

The `_meta` parameter is optional and not automatically generated or used by {es}.

To unset `_meta`, replace the pipeline without specifying one.

[source,console]
--------------------------------------------------
PUT /_ingest/pipeline/my-pipeline-id
{
  "description" : "My optional pipeline description",
  "processors" : [
    {
      "set" : {
        "description" : "My optional processor description",
        "field": "my-keyword-field",
        "value": "foo"
      }
    }
  ],
  "_meta": {
    "reason": "set my-keyword-field to foo",
    "serialization": {
      "class": "MyPipeline",
      "id": 10
    }
  }
}
--------------------------------------------------

To check the `_meta`, use the <<get-pipeline-api,get pipeline>> API.