Import objects API | Kibana Guide

› › ›

« Export objects API Resolve import errors API »

Import objects APIedit

[preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Create sets of Kibana saved objects from a file created by the export API.

For the most up-to-date API details, refer to the open API specification.

Compatibility across versionsedit

Saved objects can only be imported into the same version, a newer minor on the same major, or the next major. Exported saved objects are not backwards compatible and cannot be imported into an older version of Kibana. See the table below for compatibility examples:

Exporting version	Importing version	Compatible?
6.7.x	6.8.x	Yes
6.x.x	7.x.x	Yes
7.x.x	8.x.x	Yes
7.1.x	7.15.x	Yes
7.x.x	6.x.x	No
7.15.x	7.1.x	No
6.x.x	8.x.x	No

Requestedit

POST <kibana host>:<port>/api/saved_objects/_import

POST <kibana host>:<port>/s/<space_id>/api/saved_objects/_import

Path parametersedit

space_id: (Optional, string) An identifier for the space. If space_id is not provided in the URL, the default space is used.

Query parametersedit

createNewCopies: (Optional, boolean) Creates copies of saved objects, regenerates each object ID, and resets the origin. When used, potential conflict errors are avoided.

This option cannot be used with the overwrite and compatibilityMode options.
overwrite: (Optional, boolean) Overwrites saved objects when they already exist. When used, potential conflict errors are automatically resolved by overwriting the destination object.

This option cannot be used with the createNewCopies option.
compatibilityMode: (Optional, boolean) Applies various adjustments to the saved objects that are being imported to maintain compatibility between different Kibana versions. Use this option only if you encounter issues with imported saved objects.

This option cannot be used with the createNewCopies option.

Request bodyedit

The request body must include the multipart/form-data type.

file: A file exported using the export API.

The savedObjects.maxImportExportSize configuration setting limits the number of saved objects which may be included in this file. Similarly, the savedObjects.maxImportPayloadBytes setting limits the overall size of the file that can be imported.

Response bodyedit

success: (boolean) Indicates when the import was successfully completed. When set to false, some objects may not have been created. For additional information, refer to the errors and successResults properties.
successCount: (number) Indicates the number of successfully imported records.
errors: (Optional, array) Indicates the import was unsuccessful and specifies the objects that failed to import.

One object may result in multiple errors, which requires separate steps to resolve. For instance, a missing_references error and conflict error).
successResults: (Optional, array) Indicates the objects that are successfully imported, with any metadata if applicable.

Objects are only created when all resolvable errors are addressed, including conflicts and missing references. For information on how to resolve errors, refer to the examples.

Response codeedit

200: Indicates a successful call.

Examplesedit

Successful import with `createNewCopies` enablededit

Import a data view and dashboard:

$ curl -X POST api/saved_objects/_import?createNewCopies=true -H "kbn-xsrf: true" --form file=@file.ndjson

The file.ndjson file contains the following:

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

The API returns the following:

{
  "success": true,
  "successCount": 2,
  "successResults": [
    {
      "id": "my-pattern",
      "type": "index-pattern",
      "destinationId": "4aba3770-0d04-45e1-9e34-4cf0fd2165ae",
      "meta": {
        "icon": "indexPatternApp",
        "title": "my-pattern-*"
      }
    },
    {
      "id": "my-dashboard",
      "type": "dashboard",
      "destinationId": "c31d1eca-9bc0-4a81-b5f9-30c442824c48",
      "meta": {
        "icon": "dashboardApp",
        "title": "Look at my dashboard"
      }
    }
  ]
}

The result indicates a successful import, and both objects are created. Since these objects are created as new copies, each entry in the successResults array includes a destinationId attribute.

Successful import with `createNewCopies` disablededit

Import a data view and dashboard:

$ curl -X POST api/saved_objects/_import -H "kbn-xsrf: true" --form file=@file.ndjson

The file.ndjson file contains the following:

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

The API returns the following:

{
  "success": true,
  "successCount": 2,
  "successResults": [
    {
      "id": "my-pattern",
      "type": "index-pattern",
      "meta": {
        "icon": "indexPatternApp",
        "title": "my-pattern-*"
      }
    },
    {
      "id": "my-dashboard",
      "type": "dashboard",
      "meta": {
        "icon": "dashboardApp",
        "title": "Look at my dashboard"
      }
    }
  ]
}

The result indicates a successful import, and both objects are created.

Failed import with conflict errorsedit

Import a data view, visualization, Canvas workpad, and dashboard that include saved objects:

$ curl -X POST api/saved_objects/_import -H "kbn-xsrf: true" --form file=@file.ndjson

The file.ndjson file contains the following:

{"type":"index-pattern","id":"my-pattern","attributes":{"title":"my-pattern-*"}}
{"type":"visualization","id":"my-vis","attributes":{"title":"Look at my visualization"}}
{"type":"canvas-workpad","id":"my-canvas","attributes":{"name":"Look at my canvas"}}
{"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}}

The API returns the following:

{
  "success": false,
  "successCount": 1,
  "errors": [
    {
      "id": "my-pattern",
      "type": "index-pattern",
      "title": "my-pattern-*",
      "error": {
        "type": "conflict"
      },
      "meta": {
        "icon": "indexPatternApp",
        "title": "my-pattern-*"
      }
    },
    {
      "id": "my-visualization",
      "type": "my-vis",
      "title": "Look at my visualization",
      "error": {
        "type": "conflict",
        "destinationId": "another-vis"
      },
      "meta": {
        "icon": "visualizeApp",
        "title": "Look at my visualization"
      }
    },
    {
      "id": "my-canvas",
      "type": "canvas-workpad",
      "title": "Look at my canvas",
      "error": {
        "type": "ambiguous_conflict",
        "destinations": [
          {
            "id": "another-canvas",
            "title": "Look at another canvas",
            "updatedAt": "2020-07-08T16:36:32.377Z"
          },
          {
            "id": "yet-another-canvas",
            "title": "Look at yet another canvas",
            "updatedAt": "2020-07-05T12:29:54.849Z"
          }
        ]
      },
      "meta": {
        "icon": "canvasApp",
        "title": "Look at my canvas"
      }
    }
  ],
  "successResults": [
    {
      "id": "my-dashboard",
      "type": "dashboard",
      "meta": {
        "icon": "dashboardApp",
        "title": "Look at my dashboard"
      }
    }
  ]
}

The result indicates an unsuccessful import because the data view, visualization, Canvas workpad, and dashboard resulted in a conflict error:

A data view with the same ID already exists, which resulted in a conflict error. To resolve the error, overwrite the existing object, or skip the object.
A visualization with a different ID, but the same origin already exists, which resulted in a conflict error. The destinationId field contains the id of the other visualization, which caused the conflict. The behavior is added to make sure that new objects that can be shared between spaces behave in a similar way as legacy non-shareable objects. When a shareable object is exported and then imported into a new space, it retains its origin so that the conflicts are encountered as expected. To resolve, overwrite the specified destination object, or skip the object.
Two Canvas workpads with different IDs, but the same origin, already exist, which resulted in a conflict error. The destinations array describes the other workpads which caused the conflict. When a shareable object is exported, imported into a new space, then shared to another space where an object of the same origin exists, the conflict error occurs. To resolve, pick a destination object to overwrite, or skip the object.

Objects are created when the error is resolved using the Resolve import errors API.

Failed import with missing reference errorsedit

Import a visualization and dashboard when the data view for the visualization doesn’t exist:

$ curl -X POST api/saved_objects/_import -H "kbn-xsrf: true" --form file=@file.ndjson

The file.ndjson file contains the following:

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

The API returns the following:

{
  "success": false,
  "successCount": 1,
  "errors": [
    {
      "id": "my-vis",
      "type": "visualization",
      "title": "Look at my visualization",
      "error": {
        "type": "missing_references",
        "references": [
          {
            "type": "index-pattern",
            "id": "my-pattern-*"
          }
        ]
      },
      "meta": {
        "icon": "visualizeApp",
        "title": "Look at my visualization"
      }
    },
    {
      "id": "my-search",
      "type": "search",
      "title": "Look at my search",
      "error": {
        "type": "missing_references",
        "references": [
          {
            "type": "index-pattern",
            "id": "another-pattern-*"
          }
        ]
      },
      "meta": {
        "icon": "searchApp",
        "title": "Look at my search"
      }
    }
  ],
  "successResults": [
    {
      "id": "my-dashboard",
      "type": "dashboard",
      "meta": {
        "icon": "dashboardApp",
        "title": "Look at my dashboard"
      }
    }
  ]
}

The result indicates an unsuccessful import because the visualization and search resulted in a missing references error.

Objects are created when the errors are resolved using the Resolve import errors API.

« Export objects API Resolve import errors API »

Import objects APIedit

Compatibility across versionsedit

Requestedit

Path parametersedit

Query parametersedit

Request bodyedit

Response bodyedit

Response codeedit

Examplesedit

Successful import with createNewCopies enablededit

Successful import with createNewCopies disablededit

Failed import with conflict errorsedit

Failed import with missing reference errorsedit

Successful import with `createNewCopies` enablededit

Successful import with `createNewCopies` disablededit