kibana/docs/api/saved-objects/import.asciidoc

[[saved-objects-api-import]]
=== Import Objects

beta[This functionality is *beta*. It's on track to become a stable, permanent feature of {kib}. Caution should be exercised because it is possible a breaking change to these APIs will occur in a minor version, but we’ll avoid this wherever possible. ]

The import saved objects API enables you to create a set of Kibana saved objects from a file created by the export API.

Note: You cannot access this endpoint via the Console in Kibana.

==== Request

`POST /api/saved_objects/_import`

==== Query Parameters

`overwrite` (optional)::
  (boolean) Overwrite saved objects if they exist already

==== Request body

The request body must be of type multipart/form-data.

`file`::
  A file exported using the export API.

==== Response body

The response body will have a top level `success` property that indicates
if the import was successful or not as well as a `successCount` indicating how many records are successfully imported.
In the scenario the import wasn't successful a top level `errors` array will contain the objects that failed to import.

==== Examples

The following example imports an index pattern and dashboard.

[source,js]
--------------------------------------------------
$ curl -X POST "localhost:5601/api/saved_objects/_import" -H "kbn-xsrf: true" --form file=@file.ndjson
--------------------------------------------------

The `file.ndjson` file would contain the following.

[source,js]
--------------------------------------------------
{"type":"index-pattern","id":"my-pattern","attributes":{"title":"my-pattern-*"}}
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}}
--------------------------------------------------

A successful call returns a response code of `200` and a response body
containing a JSON structure similar to the following example:

[source,js]
--------------------------------------------------
{
  "success": true,
  "successCount": 2
}
--------------------------------------------------

The following example imports an index pattern and dashboard but has a conflict on the index pattern.

[source,js]
--------------------------------------------------
$ curl -X POST "localhost:5601/api/saved_objects/_import" -H "kbn-xsrf: true" --form file=@file.ndjson
--------------------------------------------------

The `file.ndjson` file would contain the following.

[source,js]
--------------------------------------------------
{"type":"index-pattern","id":"my-pattern","attributes":{"title":"my-pattern-*"}}
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}}
--------------------------------------------------

The call returns a response code of `200` and a response body
containing a JSON structure similar to the following example:

[source,js]
--------------------------------------------------
{
  "success": false,
  "successCount": 1,
  "errors": [
    {
      "id": "my-pattern",
      "type": "index-pattern",
      "title": "my-pattern-*",
      "error": {
        "type": "conflict"
      },
    },
  ],
}
--------------------------------------------------

The following example imports a visualization and dashboard but the index pattern for the visualization reference doesn't exist.

[source,js]
--------------------------------------------------
$ curl -X POST "localhost:5601/api/saved_objects/_import" -H "kbn-xsrf: true" --form file=@file.ndjson
--------------------------------------------------

The `file.ndjson` file would contain the following.

[source,js]
--------------------------------------------------
{"type":"visualization","id":"my-vis","attributes":{"title":"my-vis"},"references":[{"name":"ref_0","type":"index-pattern","id":"my-pattern-*"}]}
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"},"references":[{"name":"ref_0","type":"visualization","id":"my-vis"}]}
--------------------------------------------------

The call returns a response code of `200` and a response body
containing a JSON structure similar to the following example:

[source,js]
--------------------------------------------------
  "success": false,
  "successCount": 0,
  "errors": [
    {
      "id": "my-vis",
      "type": "visualization",
      "title": "my-vis",
      "error": {
        "type": "missing_references",
        "references": [
          {
            "type": "index-pattern",
            "id": "my-pattern-*"
          }
        ],
        "blocking": [
          {
            "type": "dashboard",
            "id": "my-dashboard"
          }
        ]
      }
    }
  ]
--------------------------------------------------