[role="xpack"]
[[spaces-api-copy-saved-objects]]
=== Copy saved objects to space API
++++
<titleabbrev>Copy saved objects to space</titleabbrev>
++++

experimental[] Copy saved objects between spaces.

It also allows you to automatically copy related objects, so when you copy a `dashboard`, this can automatically copy over the
associated visualizations, index patterns, and saved searches, as required.

You can request to overwrite any objects that already exist in the target space if they share an ID, or you can use the
<<spaces-api-resolve-copy-saved-objects-conflicts, Resolve copy saved objects conflicts API>> to do this on a per-object basis.

[[spaces-api-copy-saved-objects-request]]
==== {api-request-title}

`POST <kibana host>:<port>/api/spaces/_copy_saved_objects`

`POST <kibana host>:<port>/s/<space_id>/api/spaces/_copy_saved_objects`

[[spaces-api-copy-saved-objects-path-params]]
==== {api-path-parms-title}

`space_id`::
  (Optional, string) The ID of the space that contains the saved objects you want to copy. When `space_id` is unspecified in the URL, the
  default space is used.

[role="child_attributes"]
[[spaces-api-copy-saved-objects-request-body]]
==== {api-request-body-title}

`spaces`::
  (Required, string array) The IDs of the spaces where you want to copy the specified objects.

`objects`::
  (Required, object array) The saved objects to copy.
+
.Properties of `objects`
[%collapsible%open]
=====
  `type`:::
    (Required, string) The saved object type.

  `id`:::
    (Required, string) The saved object ID.
=====

`includeReferences`::
  (Optional, boolean) When set to `true`, all saved objects related to the specified saved objects will also be copied into the target
  spaces. The default value is `false`.

`createNewCopies`::
  (Optional, boolean) Creates new copies of saved objects, regenerates each object ID, and resets the origin. When used, potential conflict
  errors are avoided. The default value is `true`.
+
NOTE: This cannot be used with the `overwrite` option.

`overwrite`::
  (Optional, boolean) When set to `true`, all conflicts are automatically overidden. When a saved object with a matching `type` and `id`
  exists in the target space, that version is replaced with the version from the source space. The default value is `false`.
+
NOTE: This cannot be used with the `createNewCopies` option.

[role="child_attributes"]
[[spaces-api-copy-saved-objects-response-body]]
==== {api-response-body-title}

`<space_id>`::
  (object) An object that describes the result of the copy operation for the space. Includes the dynamic keys in the response.
+
.Properties of `<space_id>`
[%collapsible%open]
=====
  `success`:::
    (boolean) The copy operation was successful. When set to `false`, some objects may have been copied. For additional information, refer
    to the `errors` and `successResults` properties.

  `successCount`:::
    (number) The number of objects that successfully copied.

  `errors`:::
    (Optional, array) The errors that occurred during the copy operation. When errors are reported, the `success` flag is set to `false`.
+
NOTE: One object may result in multiple errors, which requires separate steps to resolve. For instance, a `missing_references` error and a
`conflict` error.
+
.Properties of `errors`
[%collapsible%open]
======
    `id`::::
      (string) The saved object ID that failed to copy.
    `type`::::
      (string) The type of saved object that failed to copy.
    `error`::::
      (object) The error that caused the copy operation to fail.
+
.Properties of `error`
[%collapsible%open]
=======
      `type`::::
        (string) The type of error. For example, `conflict`, `ambiguous_conflict`, `missing_references`, `unsupported_type`, or `unknown`.
        Errors marked as `conflict` or `ambiguous_conflict` may be resolved by using the <<spaces-api-resolve-copy-saved-objects-conflicts,
        Resolve copy saved objects conflicts API>>.
      `destinationId`::::
        (Optional, string) The destination ID that was used during the copy attempt. This is only present on `conflict` error types.
      `destinations`::::
        (Optional, array) A list of possible object destinations with `id`, `title`, and `updatedAt` fields to describe each one. This is
        only present on `ambiguous_conflict` error types.
=======
======

  `successResults`:::
    (Optional, array) Indicates successfully copied objects, with any applicable metadata.
+
NOTE: Objects are created when all resolvable errors are addressed, including conflict and missing references errors. For more information,
refer to the <<spaces-api-copy-saved-objects-example,examples>>.

=====
[[spaces-api-copy-saved-objects-example]]
==== {api-examples-title}

[[spaces-api-copy-saved-objects-example-1]]
===== Successful copy (with `createNewCopies` enabled)

Copy a dashboard with the `my-dashboard` ID, including all references from the `default` space to the `marketing` space. In this example,
the dashboard has a reference to a visualization, and that has a reference to an index pattern:

[source,sh]
----
$ curl -X POST api/spaces/_copy_saved_objects
{
  "objects": [{
    "type": "dashboard",
    "id": "my-dashboard"
  }],
  "spaces": ["marketing"],
  "includeReferences": true
}
----
// KIBANA

The API returns the following:

[source,sh]
----
{
  "marketing": {
    "success": true,
    "successCount": 3,
    "successResults": [
      {
        "id": "my-dashboard",
        "type": "dashboard",
        "destinationId": "1e127098-5b80-417f-b0f1-c60c8395358f",
        "meta": {
          "icon": "dashboardApp",
          "title": "Look at my dashboard"
        }
      },
      {
        "id": "my-vis",
        "type": "visualization",
        "destinationId": "a610ed80-1c73-4507-9e13-d3af736c8e04",
        "meta": {
          "icon": "visualizeApp",
          "title": "Look at my visualization"
        }
      },
      {
        "id": "my-index-pattern",
        "type": "index-pattern",
        "destinationId": "bc3c9c70-bf6f-4bec-b4ce-f4189aa9e26b",
        "meta": {
          "icon": "indexPatternApp",
          "title": "my-pattern-*"
        }
      }
    ]
  }
}
----

The result indicates a successful copy, and all three objects are created. Since these objects were created as new copies, each entry in the
`successResults` array includes a `destinationId` attribute.

[[spaces-api-copy-saved-objects-example-2]]
===== Successful copy (with `createNewCopies` disabled)

Copy a dashboard with the `my-dashboard` ID, including all references from the `default` space to the `marketing` space. In this example,
the dashboard has a reference to a visualization, and that has a reference to an index pattern:

[source,sh]
----
$ curl -X POST api/spaces/_copy_saved_objects
{
  "objects": [{
    "type": "dashboard",
    "id": "my-dashboard"
  }],
  "spaces": ["marketing"],
  "includeReferences": true,
  "createNewCopies": false
}
----
// KIBANA

The API returns the following:

[source,sh]
----
{
  "marketing": {
    "success": true,
    "successCount": 3,
    "successResults": [
      {
        "id": "my-dashboard",
        "type": "dashboard",
        "meta": {
          "icon": "dashboardApp",
          "title": "Look at my dashboard"
        }
      },
      {
        "id": "my-vis",
        "type": "visualization",
        "meta": {
          "icon": "visualizeApp",
          "title": "Look at my visualization"
        }
      },
      {
        "id": "my-index-pattern",
        "type": "index-pattern",
        "meta": {
          "icon": "indexPatternApp",
          "title": "my-pattern-*"
        }
      }
    ]
  }
}
----

The result indicates a successful copy, and all three objects are created.

[[spaces-api-copy-saved-objects-example-3]]
===== Failed copy (with conflict errors)

Copy a dashboard with the `my-dashboard` ID, including all references from the `default` space to the `marketing` and `sales` spaces. In
this example, the dashboard has a reference to a visualization and a *Canvas* workpad, and the visualization has a reference to an index
pattern:

[source,sh]
----
$ curl -X POST api/spaces/_copy_saved_objects
{
  "objects": [{
    "type": "dashboard",
    "id": "my-dashboard"
  }],
  "spaces": ["marketing", "sales"],
  "includeReferences": true,
  "createNewCopies": false
}
----
// KIBANA

The API returns the following:

[source,sh]
----
{
  "marketing": {
    "success": true,
    "successCount": 4,
    "successResults": [
      {
        "id": "my-dashboard",
        "type": "dashboard",
        "meta": {
          "icon": "dashboardApp",
          "title": "Look at my dashboard"
        }
      },
      {
        "id": "my-vis",
        "type": "visualization",
        "meta": {
          "icon": "visualizeApp",
          "title": "Look at my visualization"
        }
      },
      {
        "id": "my-canvas",
        "type": "canvas-workpad",
        "meta": {
          "icon": "canvasApp",
          "title": "Look at my canvas"
        }
      },
      {
        "id": "my-index-pattern",
        "type": "index-pattern",
        "meta": {
          "icon": "indexPatternApp",
          "title": "my-pattern-*"
        }
      }
    ]
  },
  "sales": {
    "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 a successful copy for the `marketing` space, and an unsuccessful copy for the `sales` space because the index pattern,
visualization, and *Canvas* workpad each resulted in a conflict error:

* An index pattern 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 copied 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 copied 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 <<spaces-api-resolve-copy-saved-objects-conflicts-example-1,Resolve copy conflicts
API>>.

[[spaces-api-copy-saved-objects-example-4]]
===== Failed copy (with missing reference errors)

Copy a dashboard with the `my-dashboard` ID, including all references from the `default` space to the `marketing` space. In this example,
the dashboard has a reference to a visualization and a *Canvas* workpad, and the visualization has a reference to an index pattern:

[source,sh]
----
$ curl -X POST api/spaces/_copy_saved_objects
{
  "objects": [{
    "type": "dashboard",
    "id": "my-dashboard"
  }],
  "spaces": ["marketing"],
  "includeReferences": true,
  "createNewCopies": false
}
----
// KIBANA

The API returns the following:

[source,sh]
----
{
  "marketing": {
    "success": false,
    "successCount": 2,
    "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"
        }
      },
    ]
    "successResults": [
      {
        "id": "my-dashboard",
        "type": "dashboard",
        "meta": {
          "icon": "dashboardApp",
          "title": "Look at my dashboard"
        }
      },
      {
        "id": "my-canvas",
        "type": "canvas-workpad",
        "meta": {
          "icon": "canvasApp",
          "title": "Look at my canvas"
        }
      }
    ],
  }
}
----

The result indicates an unsuccessful copy because the visualization resulted in a missing references error.

Objects are created when the errors are resolved using the <<spaces-api-resolve-copy-saved-objects-conflicts-example-2,Resolve copy
conflicts API>>.
