106 lines
3.9 KiB
Text
106 lines
3.9 KiB
Text
[[saved-objects-api-create]]
|
|
=== Create saved objects API
|
|
++++
|
|
<titleabbrev>Create saved objects</titleabbrev>
|
|
++++
|
|
|
|
experimental[] Create {kib} saved objects.
|
|
|
|
[[saved-objects-api-create-request]]
|
|
==== Request
|
|
|
|
`POST <kibana host>:<port>/api/saved_objects/<type>`
|
|
|
|
`POST <kibana host>:<port>/api/saved_objects/<type>/<id>`
|
|
|
|
`POST <kibana host>:<port>/s/<space_id>/api/saved_objects/<type>`
|
|
|
|
`POST <kibana host>:<port>/s/<space_id>/api/saved_objects/<type>/<id>`
|
|
|
|
[[saved-objects-api-create-path-params]]
|
|
==== Path parameters
|
|
|
|
`space_id`::
|
|
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
|
|
|
`<type>`::
|
|
(Required, string) Valid options include `visualization`, `dashboard`, `search`, `index-pattern`, `config`.
|
|
|
|
`<id>`::
|
|
(Optional, string) Specifies an ID instead of using a randomly generated ID.
|
|
|
|
[[saved-objects-api-create-query-params]]
|
|
==== Query parameters
|
|
|
|
`overwrite`::
|
|
(Optional, boolean) When true, overwrites the document with the same ID.
|
|
|
|
[[saved-objects-api-create-request-body]]
|
|
==== Request body
|
|
|
|
`attributes`::
|
|
(Required, object) The data that you want to create.
|
|
+
|
|
WARNING: When you create saved objects, attributes are not validated, which allows you to pass
|
|
arbitrary and ill-formed data into the API that can break {kib}. Make sure
|
|
any data that you send to the API is properly formed.
|
|
|
|
`references`::
|
|
(Optional, array) Objects with `name`, `id`, and `type` properties that describe the other saved objects that this object references. Use `name` in attributes to refer to the other saved object, but never the `id`, which can update automatically during migrations or import/export.
|
|
|
|
`initialNamespaces`::
|
|
(Optional, string array) Identifiers for the <<xpack-spaces,spaces>> in which this object is created. If this is provided, the
|
|
object is created only in the explicitly defined spaces. If this is not provided, the object is created in the current space
|
|
(default behavior).
|
|
* For shareable object types (registered with `namespaceType: 'multiple'`): this option can be used to specify one or more spaces, including
|
|
the "All spaces" identifier (`'*'`).
|
|
* For isolated object types (registered with `namespaceType: 'single'` or `namespaceType: 'multiple-isolated'`): this option can only be
|
|
used to specify a single space, and the "All spaces" identifier (`'*'`) is not allowed.
|
|
* For global object types (registered with `namespaceType: 'agnostic'): this option cannot be used.
|
|
|
|
[[saved-objects-api-create-request-codes]]
|
|
==== Response code
|
|
|
|
`200`::
|
|
Indicates a successful call.
|
|
|
|
`409`::
|
|
Indicates a <<saved-objects-api-create-conflict-errors,conflict error>>.
|
|
|
|
[[saved-objects-api-create-example]]
|
|
==== Example
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
$ curl -X POST api/saved_objects/index-pattern/my-pattern -H 'kbn-xsrf: true' -H 'Content-Type: application/json' -d '
|
|
{
|
|
"attributes": {
|
|
"title": "my-pattern-*"
|
|
}
|
|
}'
|
|
--------------------------------------------------
|
|
// KIBANA
|
|
|
|
The API returns the following:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
{
|
|
"id": "my-pattern", <1>
|
|
"type": "index-pattern",
|
|
"version": 1,
|
|
"attributes": {
|
|
"title": "my-pattern-*"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
<1> When `my-pattern` is unspecified in the path, a unique ID is automatically generated.
|
|
|
|
[[saved-objects-api-create-conflict-errors]]
|
|
==== Conflict errors
|
|
|
|
Starting in {kib} 8.0, saved objects can exist in multiple spaces. As a result, you may encounter different types of conflict errors when
|
|
attempting to create an object. If you encounter a 409 error that cannot be overridden by using the `overwrite: true` option, you are likely
|
|
hitting a different type of conflict error. The Create API response is limited and does not include additional metadata. You can get more
|
|
details about this error by using the <<saved-objects-api-bulk-create,Bulk create API>> instead.
|