diff --git a/docs/api/dashboard/export-dashboard.asciidoc b/docs/api/dashboard/export-dashboard.asciidoc index 7858b69d44c79..36c551dee84fc 100644 --- a/docs/api/dashboard/export-dashboard.asciidoc +++ b/docs/api/dashboard/export-dashboard.asciidoc @@ -9,7 +9,7 @@ experimental[] Export dashboards and corresponding saved objects. [[dashboard-api-export-request]] ==== Request -`GET /api/kibana/dashboards/export` +`GET :/api/kibana/dashboards/export` [[dashboard-api-export-params]] ==== Query parameters @@ -20,9 +20,9 @@ experimental[] Export dashboards and corresponding saved objects. [[dashboard-api-export-response-body]] ==== Response body -`objects`:: +`objects`:: (array) A top level property that includes the saved objects. The order of the objects is not guaranteed. Use the exact response body as the request body for the corresponding <>. - + [[dashboard-api-export-codes]] ==== Response code @@ -33,10 +33,10 @@ experimental[] Export dashboards and corresponding saved objects. [[dashboard-api-export-example]] ==== Example -[source,js] +[source,sh] -------------------------------------------------- -GET api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c <1> +$ curl -X GET "localhost:5601/api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c" <1> -------------------------------------------------- // KIBANA -<1> The dashboard ID is `942dcef0-b2cd-11e8-ad8e-85441f0c2e5c`. \ No newline at end of file +<1> The dashboard ID is `942dcef0-b2cd-11e8-ad8e-85441f0c2e5c`. diff --git a/docs/api/dashboard/import-dashboard.asciidoc b/docs/api/dashboard/import-dashboard.asciidoc index 14817719ec7ee..320859f78c617 100644 --- a/docs/api/dashboard/import-dashboard.asciidoc +++ b/docs/api/dashboard/import-dashboard.asciidoc @@ -9,7 +9,7 @@ experimental[] Import dashboards and corresponding saved objects. [[dashboard-api-import-request]] ==== Request -`POST /api/kibana/dashboards/import` +`POST :/api/kibana/dashboards/import` [[dashboard-api-import-params]] ==== Query parameters @@ -40,9 +40,9 @@ Use the complete response body from the <:/api/features` [float] [[features-api-get-codes]] @@ -23,7 +23,7 @@ experimental[] Retrieves all {kib} features. Features are used by spaces and sec The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "id": "discover", diff --git a/docs/api/logstash-configuration-management.asciidoc b/docs/api/logstash-configuration-management.asciidoc index fbb45095c214b..621b6c61dad8a 100644 --- a/docs/api/logstash-configuration-management.asciidoc +++ b/docs/api/logstash-configuration-management.asciidoc @@ -2,9 +2,9 @@ [[logstash-configuration-management-api]] == Logstash configuration management APIs -Programmatically integrate with the Logstash configuration management feature. +Programmatically integrate with Logstash configuration management. -WARNING: Do not directly access the `.logstash` index. The structure of the `.logstash` index is subject to change, which could cause your integration to break. Instead, use the Logstash configuration management APIs. +WARNING: Do not directly access the `.logstash` index. The structure of the `.logstash` index is subject to change, which could cause your integration to break. Instead, use the Logstash configuration management APIs. The following Logstash configuration management APIs are available: @@ -20,5 +20,3 @@ include::logstash-configuration-management/delete-pipeline.asciidoc[] include::logstash-configuration-management/list-pipeline.asciidoc[] include::logstash-configuration-management/create-logstash.asciidoc[] include::logstash-configuration-management/retrieve-pipeline.asciidoc[] - - diff --git a/docs/api/logstash-configuration-management/create-logstash.asciidoc b/docs/api/logstash-configuration-management/create-logstash.asciidoc index 38e0ee12a0ebf..d6ad27fe44603 100644 --- a/docs/api/logstash-configuration-management/create-logstash.asciidoc +++ b/docs/api/logstash-configuration-management/create-logstash.asciidoc @@ -9,7 +9,7 @@ experimental[] Create a centrally-managed Logstash pipeline, or update an existi [[logstash-configuration-management-api-create-request]] ==== Request -`PUT /api/logstash/pipeline/` +`PUT :/api/logstash/pipeline/` [[logstash-configuration-management-api-create-params]] ==== Path parameters @@ -39,9 +39,9 @@ experimental[] Create a centrally-managed Logstash pipeline, or update an existi [[logstash-configuration-management-api-create-example]] ==== Example -[source,js] +[source,sh] -------------------------------------------------- -PUT api/logstash/pipeline/hello-world +$ curl -X PUT "localhost:5601/api/logstash/pipeline/hello-world" { "pipeline": "input { stdin {} } output { stdout {} }", "settings": { diff --git a/docs/api/logstash-configuration-management/delete-pipeline.asciidoc b/docs/api/logstash-configuration-management/delete-pipeline.asciidoc index 15d44034b46fe..e982619ee17f4 100644 --- a/docs/api/logstash-configuration-management/delete-pipeline.asciidoc +++ b/docs/api/logstash-configuration-management/delete-pipeline.asciidoc @@ -9,7 +9,7 @@ experimental[] Delete a centrally-managed Logstash pipeline. [[logstash-configuration-management-api-delete-request]] ==== Request -`DELETE /api/logstash/pipeline/` +`DELETE :/api/logstash/pipeline/` [[logstash-configuration-management-api-delete-params]] ==== Path parameters @@ -26,9 +26,8 @@ experimental[] Delete a centrally-managed Logstash pipeline. [[logstash-configuration-management-api-delete-example]] ==== Example -[source,js] +[source,sh] -------------------------------------------------- -DELETE api/logstash/pipeline/hello-world +$ curl -X DELETE "localhost:5601/api/logstash/pipeline/hello-world" -------------------------------------------------- // KIBANA - diff --git a/docs/api/logstash-configuration-management/list-pipeline.asciidoc b/docs/api/logstash-configuration-management/list-pipeline.asciidoc index 7140c35d89853..d875ea3d95b78 100644 --- a/docs/api/logstash-configuration-management/list-pipeline.asciidoc +++ b/docs/api/logstash-configuration-management/list-pipeline.asciidoc @@ -9,14 +9,14 @@ experimental[] List all centrally-managed Logstash pipelines. [[logstash-configuration-management-api-list-request]] ==== Request -`GET /api/logstash/pipelines` +`GET :/api/logstash/pipelines` [[logstash-configuration-management-api-list-example]] ==== Example The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "pipelines": [ @@ -35,4 +35,4 @@ The API returns the following: } -------------------------------------------------- -<1> The `username` property appears when security is enabled, and depends on when the pipeline was created or last updated. \ No newline at end of file +<1> The `username` property appears when security is enabled, and depends on when the pipeline was created or last updated. diff --git a/docs/api/logstash-configuration-management/retrieve-pipeline.asciidoc b/docs/api/logstash-configuration-management/retrieve-pipeline.asciidoc index 93a1ec3aa1da5..1eb380b71c62a 100644 --- a/docs/api/logstash-configuration-management/retrieve-pipeline.asciidoc +++ b/docs/api/logstash-configuration-management/retrieve-pipeline.asciidoc @@ -9,20 +9,20 @@ experimental[] Retrieve a centrally-managed Logstash pipeline. [[logstash-configuration-management-api-retrieve-request]] ==== Request -`GET /api/logstash/pipeline/` +`GET :/api/logstash/pipeline/` [[logstash-configuration-management-api-retrieve-path-params]] ==== Path parameters `id`:: (Required, string) The pipeline ID. - + [[logstash-configuration-management-api-retrieve-example]] ==== Example The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "id": "hello-world", @@ -33,4 +33,4 @@ The API returns the following: "queue.type": "persistent" } } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/api/role-management.asciidoc b/docs/api/role-management.asciidoc index 482d1a9b3cdd3..4c4620a23943a 100644 --- a/docs/api/role-management.asciidoc +++ b/docs/api/role-management.asciidoc @@ -2,9 +2,9 @@ [[role-management-api]] == {kib} role management APIs -Manage the roles that grant <>. +Manage the roles that grant <>. -WARNING: Do not use the {ref}/security-api.html#security-role-apis[{es} role management APIs] to manage {kib} roles. +WARNING: Do not use the {ref}/security-api.html#security-role-apis[{es} role management APIs] to manage {kib} roles. The following {kib} role management APIs are available: diff --git a/docs/api/role-management/delete.asciidoc b/docs/api/role-management/delete.asciidoc index acf2e4a3e3f1f..530e1e252ef8f 100644 --- a/docs/api/role-management/delete.asciidoc +++ b/docs/api/role-management/delete.asciidoc @@ -4,26 +4,23 @@ Delete role ++++ -Delete a {kib} role. - -experimental["The underlying mechanism of enforcing role-based access control is stable, but the APIs for managing the roles are experimental."] +experimental[] Delete a {kib} role. [[role-management-api-delete-prereqs]] -==== Prerequisite +==== Prerequisite To use the delete role API, you must have the `manage_security` cluster privilege. [[role-management-api-delete-request-body]] ==== Request -`DELETE /api/security/role/my_admin_role` +`DELETE :/api/security/role/my_admin_role` [[role-management-api-delete-response-codes]] ==== Response codes `204`:: Indicates a successful call. - + `404`:: - Indicates an unsuccessful call. - \ No newline at end of file + Indicates an unsuccessful call. diff --git a/docs/api/role-management/get-all.asciidoc b/docs/api/role-management/get-all.asciidoc index 4a3dbd7734d3a..888bf0c8a137c 100644 --- a/docs/api/role-management/get-all.asciidoc +++ b/docs/api/role-management/get-all.asciidoc @@ -4,32 +4,30 @@ Get all roles ++++ -Retrieve all {kib} roles. - -experimental["The underlying mechanism of enforcing role-based access control is stable, but the APIs for managing the roles are experimental."] +experimental[] Retrieve all {kib} roles. [[role-management-api-get-prereqs]] -==== Prerequisite +==== Prerequisite To use the get role API, you must have the `manage_security` cluster privilege. [[role-management-api-retrieve-all-request-body]] ==== Request -`GET /api/security/role` +`GET :/api/security/role` [[role-management-api-retrieve-all-response-codes]] ==== Response code -`200`:: +`200`:: Indicates a successful call. - + [[role-management-api-retrieve-all-example]] ==== Example The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- [ { @@ -77,4 +75,4 @@ The API returns the following: "kibana": [ ] } ] --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/api/role-management/get.asciidoc b/docs/api/role-management/get.asciidoc index 44423b01abe5b..d1e9d1e6afa83 100644 --- a/docs/api/role-management/get.asciidoc +++ b/docs/api/role-management/get.asciidoc @@ -4,32 +4,30 @@ Get specific role ++++ -Retrieve a specific role. - -experimental["The underlying mechanism of enforcing role-based access control is stable, but the APIs for managing the roles are experimental."] +experimental[] Retrieve a specific role. [[role-management-specific-api-get-prereqs]] -==== Prerequisite +==== Prerequisite To use the get specific role API, you must have the `manage_security` cluster privilege. [[role-management-specific-api-retrieve-all-request-body]] ===== Request -`GET /api/security/role/my_restricted_kibana_role` +`GET :/api/security/role/my_restricted_kibana_role` [[role-management-specific-api-retrieve-all-response-codes]] ==== Response code -`200`:: +`200`:: Indicates a successful call. - + [[role-management-specific-api-retrieve-all-example]] ===== Example The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "name": "my_restricted_kibana_role", diff --git a/docs/api/role-management/put.asciidoc b/docs/api/role-management/put.asciidoc index a00fedf7e7ac4..59e6bc8d37eec 100644 --- a/docs/api/role-management/put.asciidoc +++ b/docs/api/role-management/put.asciidoc @@ -4,15 +4,13 @@ Create or update role ++++ -Create a new {kib} role, or update the attributes of an existing role. {kib} roles are stored in the +experimental[] Create a new {kib} role, or update the attributes of an existing role. {kib} roles are stored in the {es} native realm. -experimental["The underlying mechanism of enforcing role-based access control is stable, but the APIs for managing the roles are experimental."] - [[role-management-api-put-request]] ==== Request -`PUT /api/security/role/my_kibana_role` +`PUT :/api/security/role/my_kibana_role` [[role-management-api-put-prereqs]] ==== Prerequisite @@ -22,45 +20,45 @@ To use the create or update role API, you must have the `manage_security` cluste [[role-management-api-response-body]] ==== Request body -`metadata`:: +`metadata`:: (Optional, object) In the `metadata` object, keys that begin with `_` are reserved for system usage. -`elasticsearch`:: - (Optional, object) {es} cluster and index privileges. Valid keys include +`elasticsearch`:: + (Optional, object) {es} cluster and index privileges. Valid keys include `cluster`, `indices`, and `run_as`. For more information, see {ref}/defining-roles.html[Defining roles]. -`kibana`:: +`kibana`:: (list) Objects that specify the <> for the role: -`base` ::: +`base` ::: (Optional, list) A base privilege. When specified, the base must be `["all"]` or `["read"]`. When the `base` privilege is specified, you are unable to use the `feature` section. "all" grants read/write access to all {kib} features for the specified spaces. "read" grants read-only access to all {kib} features for the specified spaces. -`feature` ::: +`feature` ::: (object) Contains privileges for specific features. When the `feature` privileges are specified, you are unable to use the `base` section. To retrieve a list of available features, use the <>. -`spaces` ::: +`spaces` ::: (list) The spaces to apply the privileges to. To grant access to all spaces, set to `["*"]`, or omit the value. [[role-management-api-put-response-codes]] ==== Response code -`204`:: +`204`:: Indicates a successful call. ===== Examples Grant access to various features in all spaces: -[source,js] +[source,sh] -------------------------------------------------- -PUT /api/security/role/my_kibana_role +$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role" { "metadata" : { "version" : 1 @@ -127,9 +125,9 @@ PUT /api/security/role/my_kibana_role Grant dashboard-only access to only the Marketing space: -[source,js] +[source,sh] -------------------------------------------------- -PUT /api/security/role/my_kibana_role +$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role" { "metadata" : { "version" : 1 @@ -155,9 +153,9 @@ PUT /api/security/role/my_kibana_role Grant full access to all features in the Default space: -[source,js] +[source,sh] -------------------------------------------------- -PUT /api/security/role/my_kibana_role +$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role" { "metadata" : { "version" : 1 @@ -182,9 +180,9 @@ PUT /api/security/role/my_kibana_role Grant different access to different spaces: -[source,js] +[source,sh] -------------------------------------------------- -PUT /api/security/role/my_kibana_role +$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role" { "metadata" : { "version" : 1 @@ -216,11 +214,11 @@ PUT /api/security/role/my_kibana_role -------------------------------------------------- // KIBANA -Grant access to {kib} and Elasticsearch: +Grant access to {kib} and {es}: -[source,js] +[source,sh] -------------------------------------------------- -PUT /api/security/role/my_kibana_role +$ curl -X PUT "localhost:5601/api/security/role/my_kibana_role" { "metadata" : { "version" : 1 diff --git a/docs/api/saved-objects/bulk_create.asciidoc b/docs/api/saved-objects/bulk_create.asciidoc index d649684bc30f2..6c8f43bc2af84 100644 --- a/docs/api/saved-objects/bulk_create.asciidoc +++ b/docs/api/saved-objects/bulk_create.asciidoc @@ -9,10 +9,9 @@ experimental[] Create multiple {kib} saved objects. [[saved-objects-api-bulk-create-request]] ==== Request -`POST /api/saved_objects/_bulk_create` - -`POST /s//api/saved_objects/_bulk_create` +`POST :/api/saved_objects/_bulk_create` +`POST :/s//api/saved_objects/_bulk_create` [[saved-objects-api-bulk-create-path-params]] ==== Path parameters @@ -63,9 +62,9 @@ Saved objects that are unable to persist are replaced with an error object. Create an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID: -[source,js] +[source,sh] -------------------------------------------------- -POST api/saved_objects/_bulk_create +$ curl -X POST "localhost:5601/api/saved_objects/_bulk_create" [ { "type": "index-pattern", @@ -87,7 +86,7 @@ POST api/saved_objects/_bulk_create The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "saved_objects": [ diff --git a/docs/api/saved-objects/bulk_get.asciidoc b/docs/api/saved-objects/bulk_get.asciidoc index 3ef5823716d79..b67ce493a8d70 100644 --- a/docs/api/saved-objects/bulk_get.asciidoc +++ b/docs/api/saved-objects/bulk_get.asciidoc @@ -9,9 +9,9 @@ experimental[] Retrieve multiple {kib} saved objects by ID. [[saved-objects-api-bulk-get-request]] ==== Request -`POST /api/saved_objects/_bulk_get` +`POST :/api/saved_objects/_bulk_get` -`POST /s//api/saved_objects/_bulk_get` +`POST :/s//api/saved_objects/_bulk_get` [[saved-objects-api-bulk-get-path-params]] ==== Path parameters @@ -43,6 +43,7 @@ Saved objects that are unable to persist are replaced with an error object. ==== Response code `200`:: + Indicates a successful call. [[saved-objects-api-bulk-get-body-example]] @@ -50,9 +51,9 @@ Saved objects that are unable to persist are replaced with an error object. Retrieve an index pattern with the `my-pattern` ID, and a dashboard with the `my-dashboard` ID: -[source,js] +[source,sh] -------------------------------------------------- -POST api/saved_objects/_bulk_get +$ curl -X POST "localhost:5601/api/saved_objects/_bulk_get" [ { "type": "index-pattern", @@ -68,7 +69,7 @@ POST api/saved_objects/_bulk_get The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "saved_objects": [ diff --git a/docs/api/saved-objects/create.asciidoc b/docs/api/saved-objects/create.asciidoc index 634c71bb4eefe..2f35740c0f9d6 100644 --- a/docs/api/saved-objects/create.asciidoc +++ b/docs/api/saved-objects/create.asciidoc @@ -9,9 +9,11 @@ experimental[] Create {kib} saved objects. [[saved-objects-api-create-request]] ==== Request -`POST /api/saved_objects/` + +`POST :/api/saved_objects/` + -`POST /api/saved_objects//` +`POST :/api/saved_objects//` + +`POST :/s//saved_objects/` `POST /s//saved_objects/` @@ -55,9 +57,9 @@ any data that you send to the API is properly formed. [[saved-objects-api-create-example]] ==== Example -[source,js] +[source,sh] -------------------------------------------------- -POST api/saved_objects/index-pattern/my-pattern +$ curl -X POST "localhost:5601/api/saved_objects/index-pattern/my-pattern" { "attributes": { "title": "my-pattern-*" @@ -68,7 +70,7 @@ POST api/saved_objects/index-pattern/my-pattern The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "id": "my-pattern", <1> diff --git a/docs/api/saved-objects/delete.asciidoc b/docs/api/saved-objects/delete.asciidoc index c34f9b67dfd22..84f0bd85bacfb 100644 --- a/docs/api/saved-objects/delete.asciidoc +++ b/docs/api/saved-objects/delete.asciidoc @@ -4,14 +4,16 @@ Delete object ++++ -experimental[] Remove {kib} saved objects. +experimental[] Remove {kib} saved objects. WARNING: Once you delete a saved object, _it cannot be recovered_. [[saved-objects-api-delete-request]] ==== Request -`DELETE /api/saved_objects//` +`DELETE :/api/saved_objects//` + +`DELETE :/s//api/saved_objects//` `DELETE /s//api/saved_objects//` @@ -33,12 +35,12 @@ WARNING: Once you delete a saved object, _it cannot be recovered_. `200`:: Indicates a successful call. -==== Examples +==== Example Delete an index pattern object with the `my-pattern` ID: -[source,js] +[source,sh] -------------------------------------------------- -DELETE api/saved_objects/index-pattern/my-pattern +$ curl -X DELETE "localhost:5601/api/saved_objects/index-pattern/my-pattern" -------------------------------------------------- // KIBANA diff --git a/docs/api/saved-objects/export.asciidoc b/docs/api/saved-objects/export.asciidoc index 1b4f50dda2ddb..e8c762b9543a1 100644 --- a/docs/api/saved-objects/export.asciidoc +++ b/docs/api/saved-objects/export.asciidoc @@ -9,9 +9,9 @@ experimental[] Retrieve sets of saved objects that you want to import into {kib} [[saved-objects-api-export-request]] ==== Request -`POST /api/saved_objects/_export` +`POST :/api/saved_objects/_export` -`POST /s//api/saved_objects/_export` +`POST :/s//api/saved_objects/_export` [[saved-objects-api-export-path-params]] ==== Path parameters @@ -39,7 +39,7 @@ TIP: You must include `type` or `objects` in the request body. [[saved-objects-api-export-request-response-body]] ==== Response body -The format of the response body is newline delimited JSON. Each exported object is exported as a valid JSON record and separated by the newline character '\n'. +The format of the response body is newline delimited JSON. Each exported object is exported as a valid JSON record and separated by the newline character '\n'. When `excludeExportDetails=false` (the default) we append an export result details record at the end of the file after all the saved object records. The export result details object has the following format: @@ -66,9 +66,9 @@ When `excludeExportDetails=false` (the default) we append an export result detai Export all index pattern saved objects: -[source,js] +[source,sh] -------------------------------------------------- -POST api/saved_objects/_export +$ curl -X POST "localhost:5601/api/saved_objects/_export" { "type": "index-pattern" } @@ -77,9 +77,9 @@ POST api/saved_objects/_export Export all index pattern saved objects and exclude the export summary from the stream: -[source,js] +[source,sh] -------------------------------------------------- -POST api/saved_objects/_export +$ curl -X POST "localhost:5601/api/saved_objects/_export" { "type": "index-pattern", "excludeExportDetails": true @@ -89,9 +89,9 @@ POST api/saved_objects/_export Export a specific saved object: -[source,js] +[source,sh] -------------------------------------------------- -POST api/saved_objects/_export +$ curl -X POST "localhost:5601/api/saved_objects/_export" { "objects": [ { @@ -105,9 +105,9 @@ POST api/saved_objects/_export Export a specific saved object and it's related objects : -[source,js] +[source,sh] -------------------------------------------------- -POST api/saved_objects/_export +$ curl -X POST "localhost:5601/api/saved_objects/_export" { "objects": [ { diff --git a/docs/api/saved-objects/find.asciidoc b/docs/api/saved-objects/find.asciidoc index 955c50922fde7..93e60be5d4923 100644 --- a/docs/api/saved-objects/find.asciidoc +++ b/docs/api/saved-objects/find.asciidoc @@ -9,9 +9,9 @@ experimental[] Retrieve a paginated set of {kib} saved objects by various condit [[saved-objects-api-find-request]] ==== Request -`GET /api/saved_objects/_find` +`GET :/api/saved_objects/_find` -`GET /s//api/saved_objects/_find` +`GET :/s//api/saved_objects/_find` [[saved-objects-api-find-path-params]] ==== Path parameters @@ -67,15 +67,15 @@ change. Use the find API for traditional paginated results, but avoid using it t Find index patterns with titles that start with `my`: -[source,js] +[source,sh] -------------------------------------------------- -GET api/saved_objects/_find?type=index-pattern&search_fields=title&search=my* +$ curl -X GET "localhost:5601/api/saved_objects/_find?type=index-pattern&search_fields=title&search=my*" -------------------------------------------------- // KIBANA The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "total": 1, @@ -95,8 +95,8 @@ The API returns the following: For parameters that accept multiple values (e.g. `fields`), repeat the query parameter for each value: -[source,js] +[source,sh] -------------------------------------------------- -GET api/saved_objects/_find?fields=id&fields=title +$ curl -X GET "localhost:5601/api/saved_objects/_find?fields=id&fields=title" -------------------------------------------------- // KIBANA diff --git a/docs/api/saved-objects/get.asciidoc b/docs/api/saved-objects/get.asciidoc index 29f8ef67e0a83..9b012815787f1 100644 --- a/docs/api/saved-objects/get.asciidoc +++ b/docs/api/saved-objects/get.asciidoc @@ -9,7 +9,9 @@ experimental[] Retrieve a single {kib} saved object by ID. [[saved-objects-api-get-request]] ==== Request -`GET /api/saved_objects//` +`GET :/api/saved_objects//` + +`GET :/s//api/saved_objects//` `GET /s//api/saved_objects//` @@ -37,15 +39,15 @@ experimental[] Retrieve a single {kib} saved object by ID. Retrieve the index pattern object with the `my-pattern` ID: -[source,js] +[source,sh] -------------------------------------------------- -GET api/saved_objects/index-pattern/my-pattern +$ curl -X GET "localhost:5601/api/saved_objects/index-pattern/my-pattern" -------------------------------------------------- // KIBANA The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "id": "my-pattern", @@ -57,17 +59,17 @@ The API returns the following: } -------------------------------------------------- -The following example retrieves a dashboard object in the `testspace` by id. +Retrieve a dashboard object in the `testspace` by ID: -[source,js] +[source,sh] -------------------------------------------------- -GET /s/testspace/api/saved_objects/dashboard/7adfa750-4c81-11e8-b3d7-01146121b73d +$ curl -X GET "localhost:5601/s/testspace/api/saved_objects/dashboard/7adfa750-4c81-11e8-b3d7-01146121b73d" -------------------------------------------------- // KIBANA The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "id": "7adfa750-4c81-11e8-b3d7-01146121b73d", diff --git a/docs/api/saved-objects/import.asciidoc b/docs/api/saved-objects/import.asciidoc index 1a380830ed21a..b3e4c48696a17 100644 --- a/docs/api/saved-objects/import.asciidoc +++ b/docs/api/saved-objects/import.asciidoc @@ -9,9 +9,9 @@ experimental[] Create sets of {kib} saved objects from a file created by the exp [[saved-objects-api-import-request]] ==== Request -`POST /api/saved_objects/_import` +`POST :/api/saved_objects/_import` -`POST /s//api/saved_objects/_import` +`POST :/s//api/saved_objects/_import` [[saved-objects-api-import-path-params]] ==== Path parameters @@ -55,14 +55,15 @@ The request body must include the multipart/form-data type. Import an index pattern and dashboard: -[source,js] +[source,sh] -------------------------------------------------- $ curl -X POST "localhost:5601/api/saved_objects/_import" -H "kbn-xsrf: true" --form file=@file.ndjson -------------------------------------------------- +// KIBANA The `file.ndjson` file contains the following: -[source,js] +[source,sh] -------------------------------------------------- {"type":"index-pattern","id":"my-pattern","attributes":{"title":"my-pattern-*"}} {"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}} @@ -70,7 +71,7 @@ The `file.ndjson` file contains the following: The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "success": true, @@ -80,14 +81,15 @@ The API returns the following: Import an index pattern and dashboard that includes a conflict on the index pattern: -[source,js] +[source,sh] -------------------------------------------------- $ curl -X POST "localhost:5601/api/saved_objects/_import" -H "kbn-xsrf: true" --form file=@file.ndjson -------------------------------------------------- +// KIBANA The `file.ndjson` file contains the following: -[source,js] +[source,sh] -------------------------------------------------- {"type":"index-pattern","id":"my-pattern","attributes":{"title":"my-pattern-*"}} {"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}} @@ -95,7 +97,7 @@ The `file.ndjson` file contains the following: The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "success": false, @@ -115,14 +117,15 @@ The API returns the following: Import a visualization and dashboard with an index pattern for the visualization reference that doesn't exist: -[source,js] +[source,sh] -------------------------------------------------- $ curl -X POST "localhost:5601/api/saved_objects/_import" -H "kbn-xsrf: true" --form file=@file.ndjson -------------------------------------------------- +// KIBANA The `file.ndjson` file contains the following: -[source,js] +[source,sh] -------------------------------------------------- {"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"}]} @@ -130,7 +133,7 @@ The `file.ndjson` file contains the following: The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- "success": false, "successCount": 0, diff --git a/docs/api/saved-objects/resolve_import_errors.asciidoc b/docs/api/saved-objects/resolve_import_errors.asciidoc index b64e5deb361b2..ec03917390d36 100644 --- a/docs/api/saved-objects/resolve_import_errors.asciidoc +++ b/docs/api/saved-objects/resolve_import_errors.asciidoc @@ -17,9 +17,9 @@ To resolve errors, you can: [[saved-objects-api-resolve-import-errors-request]] ==== Request -`POST /api/saved_objects/_resolve_import_errors` +`POST :/api/saved_objects/_resolve_import_errors` -`POST /s//api/saved_objects/_resolve_import_errors` +`POST :/s//api/saved_objects/_resolve_import_errors` [[saved-objects-api-resolve-import-errors-path-params]] ==== Path parameters @@ -61,21 +61,22 @@ The request body must include the multipart/form-data type. Retry a dashboard import: -[source,js] +[source,sh] -------------------------------------------------- $ curl -X POST "localhost:5601/api/saved_objects/_resolve_import_errors" -H "kbn-xsrf: true" --form file=@file.ndjson --form retries='[{"type":"dashboard","id":"my-dashboard"}]' -------------------------------------------------- +// KIBANA The `file.ndjson` file contains the following: -[source,js] +[source,sh] -------------------------------------------------- {"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}} -------------------------------------------------- The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "success": true, @@ -85,14 +86,15 @@ The API returns the following: Resolve errors for a dashboard and overwrite the existing saved object: -[source,js] +[source,sh] -------------------------------------------------- $ curl -X POST "localhost:5601/api/saved_objects/_resolve_import_errors" -H "kbn-xsrf: true" --form file=@file.ndjson --form retries='[{"type":"dashboard","id":"my-dashboard","overwrite":true}]' -------------------------------------------------- +// KIBANA The `file.ndjson` file contains the following: -[source,js] +[source,sh] -------------------------------------------------- {"type":"index-pattern","id":"my-pattern","attributes":{"title":"my-pattern-*"}} {"type":"dashboard","id":"my-dashboard","attributes":{"title":"Look at my dashboard"}} @@ -100,7 +102,7 @@ The `file.ndjson` file contains the following: The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "success": true, @@ -110,21 +112,22 @@ The API returns the following: Resolve errors for a visualization by replacing the index pattern with another: -[source,js] +[source,sh] -------------------------------------------------- $ curl -X POST "localhost:5601/api/saved_objects/_resolve_import_errors" -H "kbn-xsrf: true" --form file=@file.ndjson --form retries='[{"type":"visualization","id":"my-vis","replaceReferences":[{"type":"index-pattern","from":"missing","to":"existing"}]}]' -------------------------------------------------- +// KIBANA The `file.ndjson` file contains the following: -[source,js] +[source,sh] -------------------------------------------------- {"type":"visualization","id":"my-vis","attributes":{"title":"Look at my visualization"},"references":[{"name":"ref_0","type":"index-pattern","id":"missing"}]} -------------------------------------------------- The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "success": true, diff --git a/docs/api/saved-objects/update.asciidoc b/docs/api/saved-objects/update.asciidoc index 99a9bd4ad15bb..3b45d6fea2947 100644 --- a/docs/api/saved-objects/update.asciidoc +++ b/docs/api/saved-objects/update.asciidoc @@ -9,7 +9,9 @@ experimental[] Update the attributes for existing {kib} saved objects. [[saved-objects-api-update-request]] ==== Request -`PUT /api/saved_objects//` +`PUT :/api/saved_objects//` + +`PUT :/s//api/saved_objects//` `PUT /s//api/saved_objects//` @@ -47,9 +49,9 @@ WARNING: When you update, attributes are not validated, which allows you to pass Update an existing index pattern object,`my-pattern`, with a different title: -[source,js] +[source,sh] -------------------------------------------------- -PUT api/saved_objects/index-pattern/my-pattern +$ curl -X PUT "localhost:5601/api/saved_objects/index-pattern/my-pattern" { "attributes": { "title": "some-other-pattern-*" @@ -60,7 +62,7 @@ PUT api/saved_objects/index-pattern/my-pattern The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "id": "my-pattern", diff --git a/docs/api/spaces-management/copy_saved_objects.asciidoc b/docs/api/spaces-management/copy_saved_objects.asciidoc index c07b5f35efe09..e23a137485b2d 100644 --- a/docs/api/spaces-management/copy_saved_objects.asciidoc +++ b/docs/api/spaces-management/copy_saved_objects.asciidoc @@ -5,225 +5,75 @@ Copy saved objects to space ++++ -experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."] - -//// -Use the appropriate heading levels for your book. -Add anchors for each section. -FYI: The section titles use attributes in case those terms change. -//// - -[[spaces-api-copy-saved-objects-request]] -==== {api-request-title} -//// -This section show the basic endpoint, without the body or optional parameters. -Variables should use <...> syntax. -If an API supports both PUT and POST, include both here. -//// - -`POST /api/spaces/_copy_saved_objects` - -`POST /s//api/spaces/_copy_saved_objects` - - -//// -[[spaces-api-copy-saved-objects-prereqs]] -==== {api-prereq-title} -//// -//// -Optional list of prerequisites. - -For example: - -* A snapshot of an index created in 5.x can be restored to 6.x. You must... -* If the {es} {security-features} are enabled, you must have `write`, `monitor`, -and `manage_follow_index` index privileges... -//// - - -[[spaces-api-copy-saved-objects-desc]] -==== {api-description-title} - -Copy saved objects between spaces. +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 +You can request to overwrite any objects that already exist in the target space if they share an ID, or you can use the <> to do this on a per-object basis. -//// -Add a more detailed description the context. -Link to related APIs if appropriate. +[[spaces-api-copy-saved-objects-request]] +==== {api-request-title} -Guidelines for parameter documentation -*************************************** -* Use a definition list. -* End each definition with a period. -* Include whether the parameter is Optional or Required and the data type. -* Include default values as the last sentence of the first paragraph. -* Include a range of valid values, if applicable. -* If the parameter requires a specific delimiter for multiple values, say so. -* If the parameter supports wildcards, ditto. -* For large or nested objects, consider linking to a separate definition list. -*************************************** -//// +`POST :/api/spaces/_copy_saved_objects` +`POST :/s//api/spaces/_copy_saved_objects` [[spaces-api-copy-saved-objects-path-params]] ==== {api-path-parms-title} -//// -A list of all the parameters within the path of the endpoint (before the query string (?)). -For example: -``:: -(Required, string) Name of the follower index -//// `space_id`:: -(Optional, string) Identifies the source space from which saved objects will be copied. If `space_id` is not specified in the URL, the default space is used. - -//// -[[spaces-api-copy-saved-objects-params]] -==== {api-query-parms-title} -//// -//// -A list of the parameters in the query string of the endpoint (after the ?). - -For example: -`wait_for_active_shards`:: -(Optional, integer) Specifies the number of shards to wait on being active before -responding. A shard must be restored from the leader index being active. -Restoring a follower shard requires transferring all the remote Lucene segment -files to the follower index. The default is `0`, which means waiting on none of -the shards to be active. -//// +(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. [[spaces-api-copy-saved-objects-request-body]] ==== {api-request-body-title} -//// -A list of the properties you can specify in the body of the request. -For example: -`remote_cluster`:: -(Required, string) The <> that contains -the leader index. +`spaces`:: + (Required, string array) The IDs of the spaces where you want to copy the specified objects. -`leader_index`:: -(Required, string) The name of the index in the leader cluster to follow. -//// -`spaces` :: - (Required, string array) The ids of the spaces the specified object(s) will be copied into. - -`objects` :: +`objects`:: (Required, object array) The saved objects to copy. - `type` ::: + `type`::: (Required, string) The saved object type. - `id` ::: - (Required, string) The saved object id. + `id`::: + (Required, string) The saved object ID. -`includeReferences` :: +`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`. -`overwrite` :: - (Optional, boolean) When set to `true`, all conflicts will be automatically overidden. If a saved object with a matching `type` and `id` exists in the target space, then that version will be replaced with the version from the source space. The default value is `false`. +`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`. [[spaces-api-copy-saved-objects-response-body]] ==== {api-response-body-title} -//// -Response body is only required for detailed responses. - -For example: -`auto_follow_stats`:: - (object) An object representing stats for the auto-follow coordinator. This - object consists of the following fields: - -`auto_follow_stats.number_of_successful_follow_indices`::: - (long) the number of indices that the auto-follow coordinator successfully - followed -... - -//// ``:: - (object) Specifies the dynamic keys that are included in the response. An object describing the result of the copy operation for this particular space. + (object) An object that describes the result of the copy operation for the space. Includes the dynamic keys in the response. `success`::: - (boolean) Indicates if the copy operation was successful. Note that some objects may have been copied even if this is set to `false`. Consult the `successCount` and `errors` properties of the response for additional information. + (boolean) The copy operation was successful. When set to `false`, some objects may have been copied. For additional information, refer to the `successCount` and `errors` properties. `successCount`::: - (number) The number of objects that were successfully copied. + (number) The number of objects that successfully copied. `errors`::: - (Optional, array) Collection of any errors that were encountered during the copy operation. If any errors are reported, then the `success` flag will be set to `false`. + (Optional, array) The errors that occurred during the copy operation. When errors are reported, the `success` flag is set to `false`.v `id`:::: - (string) The saved object id which failed to copy. + (string) The saved object ID that failed to copy. `type`:::: - (string) The type of saved object which failed to copy. + (string) The type of saved object that failed to copy. `error`:::: - (object) The error which caused the copy operation to fail. + (object) The error that caused the copy operation to fail. `type`::::: - (string) Indicates the type of error. May be one of: `conflict`, `unsupported_type`, `missing_references`, `unknown`. Errors marked as `conflict` may be resolved by using the <>. - -//// -[[spaces-api-copy-saved-objects-response-codes]] -==== {api-response-codes-title} -//// -//// -Response codes are only required when needed to understand the response body. - -For example: -`200`:: -Indicates all listed indices or index aliases exist. - - `404`:: -Indicates one or more listed indices or index aliases **do not** exist. -//// - + (string) The type of error. For example, `unsupported_type`, `missing_references`, or `unknown`. Errors marked as `conflict` may be resolved by using the <>. [[spaces-api-copy-saved-objects-example]] ==== {api-examples-title} -//// -Optional brief example. -Use an 'Examples' heading if you include multiple examples. +Copy a dashboard with the `my-dashboard` ID, including all references from the `default` space to the `marketing` and `sales` spaces: -[source,js] +[source,sh] ---- -PUT /follower_index/_ccr/follow?wait_for_active_shards=1 -{ - "remote_cluster" : "remote_cluster", - "leader_index" : "leader_index", - "max_read_request_operation_count" : 1024, - "max_outstanding_read_requests" : 16, - "max_read_request_size" : "1024k", - "max_write_request_operation_count" : 32768, - "max_write_request_size" : "16k", - "max_outstanding_write_requests" : 8, - "max_write_buffer_count" : 512, - "max_write_buffer_size" : "512k", - "max_retry_delay" : "10s", - "read_poll_timeout" : "30s" -} ----- -// CONSOLE -// TEST[setup:remote_cluster_and_leader_index] - -The API returns the following result: - -[source,js] ----- -{ - "follow_index_created" : true, - "follow_index_shards_acked" : true, - "index_following_started" : true -} ----- -// TESTRESPONSE -//// - -The following example attempts to copy a dashboard with id `my-dashboard`, including all references from the `default` space to the `marketing` and `sales` spaces. The `marketing` space succeeds, while the `sales` space fails due to a conflict on the underlying index pattern: - -[source,js] ----- -POST /api/spaces/_copy_saved_objects +$ curl -X POST "localhost:5601/api/spaces/_copy_saved_objects" { "objects": [{ "type": "dashboard", @@ -235,9 +85,9 @@ POST /api/spaces/_copy_saved_objects ---- // KIBANA -The API returns the following result: +The API returns the following: -[source,js] +[source,sh] ---- { "marketing": { @@ -258,11 +108,13 @@ The API returns the following result: } ---- -The following example successfully copies a visualization with id `my-viz` from the `marketing` space to the `default` space: +The `marketing` space succeeds, but the `sales` space fails due to a conflict in the index pattern. + +Copy a visualization with the `my-viz` ID from the `marketing` space to the `default` space: -[source,js] +[source,sh] ---- -POST /s/marketing/api/spaces/_copy_saved_objects +$ curl -X POST "localhost:5601/s/marketing/api/spaces/_copy_saved_objects" { "objects": [{ "type": "visualization", @@ -273,9 +125,9 @@ POST /s/marketing/api/spaces/_copy_saved_objects ---- // KIBANA -The API returns the following result: +The API returns the following: -[source,js] +[source,sh] ---- { "default": { diff --git a/docs/api/spaces-management/delete.asciidoc b/docs/api/spaces-management/delete.asciidoc index c66307ea3070f..5b4db78c056dd 100644 --- a/docs/api/spaces-management/delete.asciidoc +++ b/docs/api/spaces-management/delete.asciidoc @@ -4,22 +4,20 @@ Delete space ++++ -Delete a {kib} space. +experimental[] Delete a {kib} space. -experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."] - -WARNING: When you delete a space, all saved objects that belong to the space are automatically deleted, which is permanent and cannot be undone. +WARNING: When you delete a space, all saved objects that belong to the space are automatically deleted, which is permanent and cannot be undone. [[spaces-api-delete-request]] ==== Request -`DELETE /api/spaces/space/marketing` +`DELETE :/api/spaces/space/marketing` [[spaces-api-delete-errors-codes]] ==== Response codes -`204`:: +`204`:: Indicates a successful call. - + `404`:: Indicates that the request failed. diff --git a/docs/api/spaces-management/get.asciidoc b/docs/api/spaces-management/get.asciidoc index 49119d7602b20..48245b7786604 100644 --- a/docs/api/spaces-management/get.asciidoc +++ b/docs/api/spaces-management/get.asciidoc @@ -4,14 +4,12 @@ Get space ++++ -Retrieve a specified {kib} space. - -experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."] +experimental[] Retrieve a specified {kib} space. [[spaces-api-get-request]] ==== Request -`GET /api/spaces/space/marketing` +`GET :/api/spaces/space/marketing` [[spaces-api-get-response-codes]] ==== Response code @@ -24,7 +22,7 @@ experimental["The underlying Spaces concepts are stable, but the APIs for managi The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "id": "marketing", @@ -35,4 +33,4 @@ The API returns the following: "disabledFeatures": [], "imageUrl": "" } --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- diff --git a/docs/api/spaces-management/get_all.asciidoc b/docs/api/spaces-management/get_all.asciidoc index f7fb92baa165f..8f7ba86f332de 100644 --- a/docs/api/spaces-management/get_all.asciidoc +++ b/docs/api/spaces-management/get_all.asciidoc @@ -4,14 +4,12 @@ Get all spaces ++++ -Retrieve all {kib} spaces. - -experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."] +experimental[] Retrieve all {kib} spaces. [[spaces-api-get-all-request]] ==== Request -`GET /api/spaces/space` +`GET :/api/spaces/space` [[spaces-api-get-all-response-codes]] ==== Response code @@ -24,7 +22,7 @@ experimental["The underlying Spaces concepts are stable, but the APIs for managi The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- [ { diff --git a/docs/api/spaces-management/post.asciidoc b/docs/api/spaces-management/post.asciidoc index 4d4627e98899e..b96fbe6364c34 100644 --- a/docs/api/spaces-management/post.asciidoc +++ b/docs/api/spaces-management/post.asciidoc @@ -4,14 +4,12 @@ Create space ++++ -Create a {kib} space. - -experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."] +experimental[] Create a {kib} space. [[spaces-api-post-request]] ==== Request -`POST /api/spaces/space` +`POST :/api/spaces/space` [[spaces-api-post-request-body]] ==== Request body @@ -29,13 +27,13 @@ experimental["The underlying Spaces concepts are stable, but the APIs for managi (Optional, string array) The list of disabled features for the space. To get a list of available feature IDs, use the <>. `initials`:: - (Optional, string) Specifies the initials shown in the space avatar. By default, the initials are automatically generated from the space name. Initials must be 1 or 2 characters. + (Optional, string) The initials shown in the space avatar. By default, the initials are automatically generated from the space name. Initials must be 1 or 2 characters. `color`:: - (Optional, string) Specifies the hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name. + (Optional, string) The hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name. `imageUrl`:: - (Optional, string) Specifies the data-url encoded image to display in the space avatar. If specified, `initials` will not be displayed, and the `color` will be visible as the background color for transparent images. + (Optional, string) The data-URL encoded image to display in the space avatar. If specified, `initials` will not be displayed, and the `color` will be visible as the background color for transparent images. For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images. [[spaces-api-post-response-codes]] @@ -47,9 +45,9 @@ experimental["The underlying Spaces concepts are stable, but the APIs for managi [[spaces-api-post-example]] ==== Example -[source,js] +[source,sh] -------------------------------------------------- -POST /api/spaces/space +$ curl -X POST "localhost:5601/api/spaces/space" { "id": "marketing", "name": "Marketing", diff --git a/docs/api/spaces-management/put.asciidoc b/docs/api/spaces-management/put.asciidoc index 586818707c76f..f405d57975a70 100644 --- a/docs/api/spaces-management/put.asciidoc +++ b/docs/api/spaces-management/put.asciidoc @@ -4,37 +4,35 @@ Update space ++++ -Update an existing {kib} space. - -experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."] +experimental[] Update an existing {kib} space. [[spaces-api-put-api-request]] ==== Request -`PUT /api/spaces/space/` +`PUT :/api/spaces/space/` [[spaces-api-put-request-body]] ==== Request body -`id`:: +`id`:: (Required, string) The space ID that is part of the {kib} URL when inside the space. You are unable to change the ID with the update operation. -`name`:: +`name`:: (Required, string) The display name for the space. -`description`:: +`description`:: (Optional, string) The description for the space. -`disabledFeatures`:: +`disabledFeatures`:: (Optional, string array) The list of disabled features for the space. To get a list of available feature IDs, use the <>. -`initials`:: +`initials`:: (Optional, string) Specifies the initials shown in the space avatar. By default, the initials are automatically generated from the space name. Initials must be 1 or 2 characters. -`color`:: +`color`:: (Optional, string) Specifies the hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name. -`imageUrl`:: +`imageUrl`:: (Optional, string) Specifies the data-url encoded image to display in the space avatar. If specified, `initials` will not be displayed, and the `color` will be visible as the background color for transparent images. For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images. @@ -43,13 +41,13 @@ experimental["The underlying Spaces concepts are stable, but the APIs for managi `200`:: Indicates a successful call. - + [[sample-api-example]] ==== Example -[source,js] +[source,sh] -------------------------------------------------- -PUT /api/spaces/space/marketing +$ curl -X PUT "localhost:5601/api/spaces/space/marketing" { "id": "marketing", "name": "Marketing", diff --git a/docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc b/docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc index 7b52125599c05..8e874bb9f94e5 100644 --- a/docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc +++ b/docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc @@ -5,227 +5,80 @@ Resolve copy to space conflicts ++++ -Overwrite specific saved objects that were returned as errors from the <>. - -experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."] - -//// -Use the appropriate heading levels for your book. -Add anchors for each section. -FYI: The section titles use attributes in case those terms change. -//// +experimental[] Overwrite saved objects that are returned as errors from the <>. [[spaces-api-resolve-copy-saved-objects-conflicts-request]] ==== {api-request-title} -//// -This section show the basic endpoint, without the body or optional parameters. -Variables should use <...> syntax. -If an API supports both PUT and POST, include both here. -//// - -`POST /api/spaces/_resolve_copy_saved_objects_errors` - -`POST /s//api/spaces/_resolve_copy_saved_objects_errors` +`POST :/api/spaces/_resolve_copy_saved_objects_errors` +`POST :/s//api/spaces/_resolve_copy_saved_objects_errors` [[spaces-api-resolve-copy-saved-objects-conflicts-prereqs]] ==== {api-prereq-title} -//// -Optional list of prerequisites. - -For example: - -* A snapshot of an index created in 5.x can be restored to 6.x. You must... -* If the {es} {security-features} are enabled, you must have `write`, `monitor`, -and `manage_follow_index` index privileges... -//// -* Executed the <>, which returned one or more `conflict` errors that you wish to resolve. - -//// -[[spaces-api-resolve-copy-saved-objects-conflicts-desc]] -==== {api-description-title} - -Allows saved objects to be selectively overridden in the target spaces. -//// - -//// -Add a more detailed description the context. -Link to related APIs if appropriate. - -Guidelines for parameter documentation -*************************************** -* Use a definition list. -* End each definition with a period. -* Include whether the parameter is Optional or Required and the data type. -* Include default values as the last sentence of the first paragraph. -* Include a range of valid values, if applicable. -* If the parameter requires a specific delimiter for multiple values, say so. -* If the parameter supports wildcards, ditto. -* For large or nested objects, consider linking to a separate definition list. -*************************************** -//// +Execute the <>, which returns the errors for you to resolve. [[spaces-api-resolve-copy-saved-objects-conflicts-path-params]] ==== {api-path-parms-title} -//// -A list of all the parameters within the path of the endpoint (before the query string (?)). -For example: -``:: -(Required, string) Name of the follower index -//// `space_id`:: -(Optional, string) Identifies the source space from which saved objects will be copied. If `space_id` is not specified in the URL, the default space is used. Must be the same value that was used during the failed <> operation. - -//// -[[spaces-api-resolve-copy-saved-objects-conflicts-request-params]] -==== {api-query-parms-title} -//// -//// -A list of the parameters in the query string of the endpoint (after the ?). - -For example: -`wait_for_active_shards`:: -(Optional, integer) Specifies the number of shards to wait on being active before -responding. A shard must be restored from the leader index being active. -Restoring a follower shard requires transferring all the remote Lucene segment -files to the follower index. The default is `0`, which means waiting on none of -the shards to be active. -//// +(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. The `space_id` must be the same value used during the failed <> operation. [[spaces-api-resolve-copy-saved-objects-conflicts-request-body]] ==== {api-request-body-title} -//// -A list of the properties you can specify in the body of the request. - -For example: -`remote_cluster`:: -(Required, string) The <> that contains -the leader index. -`leader_index`:: -(Required, string) The name of the index in the leader cluster to follow. -//// -`objects` :: - (Required, object array) The saved objects to copy. Must be the same value that was used during the failed <> operation. - `type` ::: +`objects`:: + (Required, object array) The saved objects to copy. The `objects` must be the same values used during the failed <> operation. + `type`::: (Required, string) The saved object type. - `id` ::: - (Required, string) The saved object id. + `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. You must set this to the same value that you used when executing the <>. The default value is `false`. +`includeReferences`:: + (Optional, boolean) When set to `true`, all saved objects related to the specified saved objects are copied into the target spaces. The `includeReferences` must be the same values used during the failed <> operation. The default value is `false`. `retries`:: - (Required, object) The retry operations to attempt. Object keys represent the target space ids. - `` ::: - (Required, array) The the conflicts to resolve for the indicated ``. - `type` :::: + (Required, object) The retry operations to attempt. Object keys represent the target space IDs. + ``::: + (Required, array) The errors to resolve for the specified ``. + `type`:::: (Required, string) The saved object type. - `id` :::: - (Required, string) The saved object id. - `overwrite` :::: - (Required, boolean) when set to `true`, the saved object from the source space (desigated by the <>) will overwrite the the conflicting object in the destination space. When `false`, this does nothing. + `id`:::: + (Required, string) The saved object ID. + `overwrite`:::: + (Required, boolean) When set to `true`, the saved object from the source space (desigated by the <>) overwrites the conflicting object in the destination space. When set to `false`, this does nothing. [[spaces-api-resolve-copy-saved-objects-conflicts-response-body]] ==== {api-response-body-title} -//// -Response body is only required for detailed responses. - -For example: -`auto_follow_stats`:: - (object) An object representing stats for the auto-follow coordinator. This - object consists of the following fields: - -`auto_follow_stats.number_of_successful_follow_indices`::: - (long) the number of indices that the auto-follow coordinator successfully - followed -... - -//// ``:: - (object) Specifies the dynamic keys that are included in the response. An object describing the result of the copy operation for this particular space. + (object) An object that describes the result of the copy operation for the space. Includes the dynamic keys in the response. `success`::: - (boolean) Indicates if the copy operation was successful. Note that some objects may have been copied even if this is set to `false`. Consult the `successCount` and `errors` properties of the response for additional information. + (boolean) The copy operation was successful. When set to `false`, some objects may have been copied. For additional information, refer to the `successCount` and `errors` properties. `successCount`::: - (number) The number of objects that were successfully copied. + (number) The number of objects that successfully copied. `errors`::: - (Optional, array) Collection of any errors that were encountered during the copy operation. If any errors are reported, then the `success` flag will be set to `false`. + (Optional, array) The errors that occurred during the copy operation. When errors are reported, the `success` flag is set to `false`. `id`:::: - (string) The saved object id which failed to copy. + (string) The saved object ID that failed to copy. `type`:::: - (string) The type of saved object which failed to copy. + (string) The type of saved object that failed to copy. `error`:::: - (object) The error which caused the copy operation to fail. + (object) The error that caused the copy operation to fail. `type`::::: - (string) Indicates the type of error. May be one of: `unsupported_type`, `missing_references`, `unknown`. - -//// -[[spaces-api-resolve-copy-saved-objects-conflicts-response-codes]] -==== {api-response-codes-title} -//// -//// -Response codes are only required when needed to understand the response body. - -For example: -`200`:: -Indicates all listed indices or index aliases exist. - - `404`:: -Indicates one or more listed indices or index aliases **do not** exist. -//// + (string) The type of error. For example, `unsupported_type`, `missing_references`, or `unknown`. [[spaces-api-resolve-copy-saved-objects-conflicts-example]] ==== {api-examples-title} -//// -Optional brief example. -Use an 'Examples' heading if you include multiple examples. - - -[source,js] ----- -PUT /follower_index/_ccr/follow?wait_for_active_shards=1 -{ - "remote_cluster" : "remote_cluster", - "leader_index" : "leader_index", - "max_read_request_operation_count" : 1024, - "max_outstanding_read_requests" : 16, - "max_read_request_size" : "1024k", - "max_write_request_operation_count" : 32768, - "max_write_request_size" : "16k", - "max_outstanding_write_requests" : 8, - "max_write_buffer_count" : 512, - "max_write_buffer_size" : "512k", - "max_retry_delay" : "10s", - "read_poll_timeout" : "30s" -} ----- -// CONSOLE -// TEST[setup:remote_cluster_and_leader_index] - -The API returns the following result: - -[source,js] ----- -{ - "follow_index_created" : true, - "follow_index_shards_acked" : true, - "index_following_started" : true -} ----- -// TESTRESPONSE -//// -The following example overwrites an index pattern in the marketing space, and a visualization in the sales space. +Overwrite an index pattern in the `marketing` space, and a visualization in the `sales` space: -[source,js] +[source,sh] ---- -POST api/spaces/_resolve_copy_saved_objects_errors +$ curl -X POST "localhost:5601/api/spaces/_resolve_copy_saved_objects_errors" { "objects": [{ "type": "dashboard", @@ -248,9 +101,9 @@ POST api/spaces/_resolve_copy_saved_objects_errors ---- // KIBANA -The API returns the following result: +The API returns the following: -[source,js] +[source,sh] ---- { "marketing": { diff --git a/docs/api/upgrade-assistant.asciidoc b/docs/api/upgrade-assistant.asciidoc index 3e9c416b292cf..15d87fbd0dc9d 100644 --- a/docs/api/upgrade-assistant.asciidoc +++ b/docs/api/upgrade-assistant.asciidoc @@ -2,7 +2,7 @@ [[upgrade-assistant-api]] == Upgrade assistant APIs -Check the upgrade status of your Elasticsearch cluster and reindex indices that were created in the previous major version. The assistant helps you prepare for the next major version of Elasticsearch. +Check the upgrade status of your {es} cluster and reindex indices that were created in the previous major version. The assistant helps you prepare for the next major version of {es}. The following upgrade assistant APIs are available: @@ -16,7 +16,7 @@ The following upgrade assistant APIs are available: * <> to check the status of the reindex operation -* <> to cancel reindexes that are waiting for the Elasticsearch reindex task to complete +* <> to cancel reindexes that are waiting for the {es} reindex task to complete include::upgrade-assistant/status.asciidoc[] include::upgrade-assistant/reindexing.asciidoc[] diff --git a/docs/api/upgrade-assistant/cancel_reindex.asciidoc b/docs/api/upgrade-assistant/cancel_reindex.asciidoc index d31894cd06a05..04ab3bdde35fc 100644 --- a/docs/api/upgrade-assistant/cancel_reindex.asciidoc +++ b/docs/api/upgrade-assistant/cancel_reindex.asciidoc @@ -4,14 +4,14 @@ Cancel reindex ++++ -experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."] +experimental[] Cancel reindexes that are waiting for the {es} reindex task to complete. For example, `lastCompletedStep` set to `40`. Cancel reindexes that are waiting for the Elasticsearch reindex task to complete. For example, `lastCompletedStep` set to `40`. [[cancel-reindex-request]] ==== Request -`POST /api/upgrade_assistant/reindex/myIndex/cancel` +`POST :/api/upgrade_assistant/reindex/myIndex/cancel` [[cancel-reindex-response-codes]] ==== Response codes @@ -24,7 +24,7 @@ Cancel reindexes that are waiting for the Elasticsearch reindex task to complete The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "acknowledged": true diff --git a/docs/api/upgrade-assistant/check_reindex_status.asciidoc b/docs/api/upgrade-assistant/check_reindex_status.asciidoc index c422e5764c69f..00801f201d1e1 100644 --- a/docs/api/upgrade-assistant/check_reindex_status.asciidoc +++ b/docs/api/upgrade-assistant/check_reindex_status.asciidoc @@ -4,27 +4,27 @@ Check reindex status ++++ -experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."] +experimental[] Check the status of the reindex operation. Check the status of the reindex operation. [[check-reindex-status-request]] ==== Request -`GET /api/upgrade_assistant/reindex/myIndex` +`GET :/api/upgrade_assistant/reindex/myIndex` [[check-reindex-status-response-codes]] ==== Response codes `200`:: Indicates a successful call. - + [[check-reindex-status-example]] ==== Example The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "reindexOp": { @@ -53,59 +53,58 @@ The API returns the following: [[status-code]] ==== Status codes -`0`:: +`0`:: In progress -`1`:: +`1`:: Completed -`2`:: +`2`:: Failed - -`3`:: + +`3`:: Paused NOTE: If the {kib} node that started the reindex is shutdown or restarted, the reindex goes into a paused state after some time. To resume the reindex, you must submit a new POST request to the `/api/upgrade_assistant/reindex/` endpoint. -`4`:: +`4`:: Cancelled [[step-code]] ==== Step codes -`0`:: +`0`:: The reindex operation has been created in Kibana. - -`10`:: + +`10`:: The index group services stopped. Only applies to some system indices. - -`20`:: - The index is set to `readonly`. - -`30`:: + +`20`:: + The index is set to `readonly`. + +`30`:: The new destination index has been created. - -`40`:: + +`40`:: The reindex task in Elasticsearch has started. - -`50`:: + +`50`:: The reindex task in Elasticsearch has completed. - -`60`:: + +`60`:: Aliases were created to point to the new index, and the old index has been deleted. - -`70`:: + +`70`:: The index group services have resumed. Only applies to some system indices. [[warning-code]] ==== Warning codes -`0`:: +`0`:: Specifies to remove the `_all` meta field. - -`1`:: + +`1`:: Specifies to convert any coerced boolean values in the source document. For example, `yes`, `1`, and `off`. - -`2`:: - Specifies to convert documents to support Elastic Common Schema. Only applies to APM indices created in 6.x. +`2`:: + Specifies to convert documents to support Elastic Common Schema. Only applies to APM indices created in 6.x. diff --git a/docs/api/upgrade-assistant/reindexing.asciidoc b/docs/api/upgrade-assistant/reindexing.asciidoc index 51e7b917b67ac..ce5670822e5ad 100644 --- a/docs/api/upgrade-assistant/reindexing.asciidoc +++ b/docs/api/upgrade-assistant/reindexing.asciidoc @@ -4,14 +4,14 @@ Start or resume reindex ++++ -experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."] +experimental[] Start a new reindex or resume a paused reindex. Start a new reindex or resume a paused reindex. [[start-resume-reindex-request]] ==== Request -`POST /api/upgrade_assistant/reindex/myIndex` +`POST :/api/upgrade_assistant/reindex/myIndex` [[start-resume-reindex-codes]] ==== Response code @@ -24,7 +24,7 @@ Start a new reindex or resume a paused reindex. The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "indexName": ".ml-state", @@ -37,9 +37,9 @@ The API returns the following: } -------------------------------------------------- -<1> Name of the new index that is being created. -<2> Current status of the reindex. For details, see <>. -<3> Last successfully completed step of the reindex. For details, see <> table. -<4> Task ID of the reindex task in Elasticsearch. Only present if reindexing has started. -<5> Percentage of how far the reindexing task in Elasticsearch has progressed, in decimal from from 0 to 1. -<6> Error that caused the reindex to fail, if it failed. +<1> The name of the new index. +<2> The reindex status. For more information, refer to <>. +<3> The last successfully completed step of the reindex. For more information, refer to <>. +<4> The task ID of the reindex task in {es}. Appears when the reindexing starts. +<5> The progress of the reindexing task in {es}. Appears in decimal form, from 0 to 1. +<6> The error that caused the reindex to fail, if it failed. diff --git a/docs/api/upgrade-assistant/status.asciidoc b/docs/api/upgrade-assistant/status.asciidoc index b087a66fa3bcd..42030061c4289 100644 --- a/docs/api/upgrade-assistant/status.asciidoc +++ b/docs/api/upgrade-assistant/status.asciidoc @@ -4,14 +4,14 @@ Upgrade readiness status ++++ -experimental["The underlying Upgrade Assistant concepts are stable, but the APIs for managing Upgrade Assistant are experimental."] +experimental[] Check the status of your cluster. Check the status of your cluster. [[upgrade-assistant-api-status-request]] ==== Request -`GET /api/upgrade_assistant/status` +`GET :/api/upgrade_assistant/status` [[upgrade-assistant-api-status-response-codes]] ==== Response codes @@ -24,7 +24,7 @@ Check the status of your cluster. The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "readyForUpgrade": false, diff --git a/docs/api/url-shortening.asciidoc b/docs/api/url-shortening.asciidoc index 8bc701a3d5d12..a62529e11a9ba 100644 --- a/docs/api/url-shortening.asciidoc +++ b/docs/api/url-shortening.asciidoc @@ -12,18 +12,18 @@ Short URLs are designed to make sharing {kib} URLs easier. [[url-shortening-api-request]] ==== Request -`POST /api/shorten_url` +`POST :/api/shorten_url` [[url-shortening-api-request-body]] ==== Request body `url`:: - (Required, string) The {kib} URL that you want to shorten, Relative to `/app/kibana`. + (Required, string) The {kib} URL that you want to shorten, relative to `/app/kibana`. [[url-shortening-api-response-body]] ==== Response body -urlId:: A top level property that contains the shortened URL token for the provided request body. +urlId:: A top-level property that contains the shortened URL token for the provided request body. [[url-shortening-api-codes]] ==== Response code @@ -31,21 +31,21 @@ urlId:: A top level property that contains the shortened URL token for the provi `200`:: Indicates a successful call. -[[url-shortening-api-example]] +[[url-shortening-api-example]] ==== Example -[source,js] +[source,sh] -------------------------------------------------- -POST api/shorten_url +$ curl -X POST "localhost:5601/api/shorten_url" { "url": "/app/kibana#/dashboard?_g=()&_a=(description:'',filters:!(),fullScreenMode:!f,options:(hidePanelTitles:!f,useMargins:!t),panels:!((embeddableConfig:(),gridData:(h:15,i:'1',w:24,x:0,y:0),id:'8f4d0c00-4c86-11e8-b3d7-01146121b73d',panelIndex:'1',type:visualization,version:'7.0.0-alpha1')),query:(language:lucene,query:''),timeRestore:!f,title:'New%20Dashboard',viewMode:edit)" } -------------------------------------------------- // KIBANA -The API returns the following result: +The API returns the following: -[source,js] +[source,sh] -------------------------------------------------- { "urlId": "f73b295ff92718b26bc94edac766d8e3" diff --git a/docs/api/using-api.asciidoc b/docs/api/using-api.asciidoc index 37c5315025dc4..aba65f2e921c2 100644 --- a/docs/api/using-api.asciidoc +++ b/docs/api/using-api.asciidoc @@ -33,6 +33,7 @@ For example, the following `curl` command exports a dashboard: -- curl -X POST -u $USER:$PASSWORD "localhost:5601/api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c" -- +// KIBANA [float] [[api-request-headers]] @@ -43,14 +44,14 @@ For all APIs, you must use a request header. The {kib} APIs support the `kbn-xsr `kbn-xsrf: true`:: By default, you must use `kbn-xsrf` for all API calls, except in the following scenarios: -* The API endpoint uses the `GET` or `HEAD` methods +* The API endpoint uses the `GET` or `HEAD` operations * The path is whitelisted using the <> setting * XSRF protections are disabled using the `server.xsrf.disableProtection` setting `Content-Type: application/json`:: - Applicable only when you send a payload in the API request. {kib} API requests and responses use JSON. Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header. + Applicable only when you send a payload in the API request. {kib} API requests and responses use JSON. Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header. Request header example: