[DOCS] API intro (#47164) (#48460)

* [DOCS] API intro

* Logstash configuration management

* Reformatting

* Comments from Josh

* Commets from Gail

* Fixed broken things

docs/api/dashboard-api.asciidoc

@@ -0,0 +1,17 @@
+[[dashboard-api]]
+== Import and export dashboard APIs
+
+Import and export dashboards with the corresponding saved objects, such as visualizations, saved
+searches, and index patterns.
+
+WARNING: Do not write documents directly to the `.kibana` index. When you write directly
+to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions.
+
+The following import and export dashboard APIs are available:
+
+* <<dashboard-import-api, Import dashboard API>> to import dashboards and corresponding saved objects
+
+* <<dashboard-api-export, Export dashboard API>> to export dashboards and corresponding saved objects
+
+include::dashboard/import-dashboard.asciidoc[]
+include::dashboard/export-dashboard.asciidoc[]

docs/api/dashboard-import.asciidoc

@@ -1,14 +0,0 @@
-[[dashboard-import-api]]
-== Dashboard import and export APIs
-
-Import and export dashboards with the corresponding saved objects, such as visualizations, saved
-searches, and index patterns.
-
-WARNING: Do not write documents directly to the `.kibana` index. When you write directly
-to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions.
-
-* <<dashboard-import-api-import, Import dashboard API>>
-* <<dashboard-api-export, Export dashboard API>>
-
-include::dashboard-import/import.asciidoc[]
-include::dashboard-import/export.asciidoc[]

docs/api/dashboard/export-dashboard.asciidoc

@@ -1,7 +1,7 @@
 [[dashboard-api-export]]
 === Export dashboard API
 ++++
-<titleabbrev>Dashboard export</titleabbrev>
+<titleabbrev>Export dashboard</titleabbrev>
 ++++
 
 experimental[] Export dashboards and corresponding saved objects.
@@ -21,7 +21,7 @@ experimental[] Export dashboards and corresponding saved objects.
 ==== Response body
 
 `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-import-api-import, Import dashboard API>>.
+  (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-import-api, Import dashboard API>>.
   
 [[dashboard-api-export-codes]]
 ==== Response code
@@ -39,4 +39,4 @@ GET api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c
 --------------------------------------------------
 // KIBANA
 
-<1> In this example, `942dcef0-b2cd-11e8-ad8e-85441f0c2e5c` is the dashboard ID.
+<1> The dashboard ID is `942dcef0-b2cd-11e8-ad8e-85441f0c2e5c`.

docs/api/dashboard/import-dashboard.asciidoc

@@ -1,4 +1,4 @@
-[[dashboard-import-api-import]]
+[[dashboard-import-api]]
 === Import dashboard API
 ++++
 <titleabbrev>Import dashboard</titleabbrev>

docs/api/features.asciidoc

@@ -1,9 +1,217 @@
 [role="xpack"]
-[[features-api]]
+[[features-api-get]]
-== Features API
+== Get features API
 
-View information about the available features in {kib}. Features are used by spaces and security to refine and secure access to {kib}.
+experimental[] Retrieves all {kib} features. Features are used by spaces and security to refine and secure access to {kib}.
 
-* <<features-api-get, Get features API>>
+[float]
+[[features-api-get-request]]
+=== Request
 
-include::features/get.asciidoc[]
+`GET /api/features`
+
+[float]
+[[features-api-get-codes]]
+=== Response code
+
+`200`::
+  Indicates a successful call.
+
+[float]
+[[features-api-get-example]]
+=== Example
+
+The API returns the following:
+
+[source,js]
+--------------------------------------------------
+  {
+    "id": "discover",
+    "name": "Discover",
+    "icon": "discoverApp",
+    "navLinkId": "kibana:discover",
+    "app": [
+      "kibana"
+    ],
+    "catalogue": [
+      "discover"
+    ],
+    "privileges": {
+      "all": {
+        "savedObject": {
+          "all": [
+            "search",
+            "url"
+          ],
+          "read": [
+            "config",
+            "index-pattern"
+          ]
+        },
+        "ui": [
+          "show",
+          "createShortUrl",
+          "save"
+        ]
+      },
+      "read": {
+        "savedObject": {
+          "all": [],
+          "read": [
+            "config",
+            "index-pattern",
+            "search",
+            "url"
+          ]
+        },
+        "ui": [
+          "show"
+        ]
+      }
+    }
+  },
+  {
+    "id": "visualize",
+    "name": "Visualize",
+    "icon": "visualizeApp",
+    "navLinkId": "kibana:visualize",
+    "app": [
+      "kibana"
+    ],
+    "catalogue": [
+      "visualize"
+    ],
+    "privileges": {
+      "all": {
+        "savedObject": {
+          "all": [
+            "visualization",
+            "url"
+          ],
+          "read": [
+            "config",
+            "index-pattern",
+            "search"
+          ]
+        },
+        "ui": [
+          "show",
+          "createShortUrl",
+          "delete",
+          "save"
+        ]
+      },
+      "read": {
+        "savedObject": {
+          "all": [],
+          "read": [
+            "config",
+            "index-pattern",
+            "search",
+            "visualization"
+          ]
+        },
+        "ui": [
+          "show"
+        ]
+      }
+    }
+  },
+  {
+    "id": "dashboard",
+    "name": "Dashboard",
+    "icon": "dashboardApp",
+    "navLinkId": "kibana:dashboard",
+    "app": [
+      "kibana"
+    ],
+    "catalogue": [
+      "dashboard"
+    ],
+    "privileges": {
+      "all": {
+        "savedObject": {
+          "all": [
+            "dashboard",
+            "url"
+          ],
+          "read": [
+            "config",
+            "index-pattern",
+            "search",
+            "visualization",
+            "timelion-sheet",
+            "canvas-workpad"
+          ]
+        },
+        "ui": [
+          "createNew",
+          "show",
+          "showWriteControls"
+        ]
+      },
+      "read": {
+        "savedObject": {
+          "all": [],
+          "read": [
+            "config",
+            "index-pattern",
+            "search",
+            "visualization",
+            "timelion-sheet",
+            "canvas-workpad",
+            "dashboard"
+          ]
+        },
+        "ui": [
+          "show"
+        ]
+      }
+    }
+  },
+  {
+    "id": "dev_tools",
+    "name": "Dev Tools",
+    "icon": "devToolsApp",
+    "navLinkId": "kibana:dev_tools",
+    "app": [
+      "kibana"
+    ],
+    "catalogue": [
+      "console",
+      "searchprofiler",
+      "grokdebugger"
+    ],
+    "privileges": {
+      "all": {
+        "api": [
+          "console"
+        ],
+        "savedObject": {
+          "all": [],
+          "read": [
+            "config"
+          ]
+        },
+        "ui": [
+          "show"
+        ]
+      },
+      "read": {
+        "api": [
+          "console"
+        ],
+        "savedObject": {
+          "all": [],
+          "read": [
+            "config"
+          ]
+        },
+        "ui": [
+          "show"
+        ]
+      }
+    },
+    "privilegesTooltip": "User should also be granted the appropriate Elasticsearch cluster and index privileges"
+  },
+--------------------------------------------------

docs/api/logstash-configuration-management.asciidoc

@@ -6,12 +6,19 @@ Programmatically integrate with the Logstash configuration management feature.
 
 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. 
 
-* <<logstash-configuration-management-api-create, Create Logstash pipeline API>>
+The following Logstash configuration management APIs are available:
-* <<logstash-configuration-management-api-retrieve, Retrieve pipeline API>>
+
-* <<logstash-configuration-management-api-delete, Delete Logstash pipeline API>>
+* <<logstash-configuration-management-api-delete, Delete Logstash pipeline API>> to delete a centrally-managed Logstash pipeline
-* <<logstash-configuration-management-api-list, List Logstash pipeline API>>
+
+* <<logstash-configuration-management-api-list, List Logstash pipeline API>> to list all centrally-managed Logstash pipelines
+
+* <<logstash-configuration-management-api-create, Create Logstash pipeline API>> to create a centrally-managed Logstash pipeline, or update an existing pipeline
+
+* <<logstash-configuration-management-api-retrieve, Retrieve pipeline API>> to retrieve a centrally-managed Logstash pipeline
+
+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[]
+
 
-include::logstash-configuration-management/create.asciidoc[]
-include::logstash-configuration-management/retrieve.asciidoc[]
-include::logstash-configuration-management/delete.asciidoc[]
-include::logstash-configuration-management/list.asciidoc[]

docs/api/logstash-configuration-management/create-logstash.asciidoc

@@ -1,8 +1,7 @@
-[role="xpack"]
 [[logstash-configuration-management-api-create]]
 === Create Logstash pipeline API
 ++++
-<titleabbrev>Create pipeline</titleabbrev>
+<titleabbrev>Create Logstash pipeline</titleabbrev>
 ++++
 
 experimental[] Create a centrally-managed Logstash pipeline, or update an existing pipeline.

docs/api/logstash-configuration-management/delete-pipeline.asciidoc

@@ -1,4 +1,3 @@
-[role="xpack"]
 [[logstash-configuration-management-api-delete]]
 === Delete Logstash pipeline API
 ++++
@@ -31,4 +30,5 @@ experimental[] Delete a centrally-managed Logstash pipeline.
 --------------------------------------------------
 DELETE api/logstash/pipeline/hello-world
 --------------------------------------------------
-// KIBANA
+// KIBANA
+

docs/api/logstash-configuration-management/list-pipeline.asciidoc

@@ -1,4 +1,3 @@
-[role="xpack"]
 [[logstash-configuration-management-api-list]]
 === List Logstash pipeline API
 ++++
@@ -36,4 +35,4 @@ The API returns the following:
 }
 --------------------------------------------------
 
-<1> The `username` property may or may not be present, depending on if security was enabled when the pipeline was created or last updated.
+<1> The `username` property appears when security is enabled, and depends on when the pipeline was created or last updated.

docs/api/logstash-configuration-management/retrieve-pipeline.asciidoc

@@ -1,11 +1,10 @@
-[role="xpack"]
 [[logstash-configuration-management-api-retrieve]]
 === Retrieve pipeline API
 ++++
 <titleabbrev>Retrieve pipeline</titleabbrev>
 ++++
 
-experimental[] Retrieves a centrally-managed Logstash pipeline.
+experimental[] Retrieve a centrally-managed Logstash pipeline.
 
 [[logstash-configuration-management-api-retrieve-request]]
 ==== Request
@@ -34,4 +33,4 @@ The API returns the following:
     "queue.type": "persistent"
   }
 }
---------------------------------------------------
+--------------------------------------------------

docs/api/role-management.asciidoc

@@ -1,15 +1,20 @@
 [role="xpack"]
 [[role-management-api]]
-== Kibana role management APIs
+== {kib} role management APIs
 
 Manage the roles that grant <<kibana-privileges, Kibana privileges>>.
 
 WARNING: Do not use the {ref}/security-api.html#security-role-apis[{es} role management APIs] to manage {kib} roles. 
 
-* <<role-management-api-put, Create or update role API>>
+The following {kib} role management APIs are available:
-* <<role-management-api-get, Get all {kib} roles API>>
+
-* <<role-management-specific-api-get, Get specific role API>>
+* <<role-management-api-put, Create or update role API>> to create a new {kib} role, or update the attributes of an existing role
-* <<role-management-api-delete, Delete role API>>
+
+* <<role-management-api-get, Get all {kib} roles API>> to retrieve all {kib} roles
+
+* <<role-management-specific-api-get, Get specific role API>> to retrieve a specific role
+
+* <<role-management-api-delete, Delete role API>> to delete a {kib} role
 
 include::role-management/put.asciidoc[]
 include::role-management/get.asciidoc[]

docs/api/role-management/delete.asciidoc

@@ -4,7 +4,7 @@
 <titleabbrev>Delete role</titleabbrev>
 ++++
 
-Deletes a {kib} 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."]
 

docs/api/role-management/get-all.asciidoc

@@ -4,7 +4,7 @@
 <titleabbrev>Get all roles</titleabbrev>
 ++++
 
-Retrieves all {kib} 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."]
 

docs/api/role-management/get.asciidoc

@@ -4,7 +4,7 @@
 <titleabbrev>Get specific role</titleabbrev>
 ++++
 
-Retrieves a 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."]
 

docs/api/role-management/put.asciidoc

@@ -4,7 +4,7 @@
 <titleabbrev>Create or update role</titleabbrev>
 ++++
 
-Creates a new {kib} role, or updates the attributes of an existing role. {kib} roles are stored in the
+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."]
@@ -40,7 +40,7 @@ To use the create or update role API, you must have the `manage_security` cluste
 `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 <<features-api, features API>>.
+  To retrieve a list of available features, use the <<features-api-get, features API>>.
 
 `spaces` ::: 
   (list) The spaces to apply the privileges to.

docs/api/saved-objects.asciidoc

@@ -6,16 +6,27 @@ Manage {kib} saved objects, including dashboards, visualizations, index patterns
 WARNING: Do not write documents directly to the `.kibana` index. When you write directly
 to the `.kibana` index, the data becomes corrupted and permanently breaks future {kib} versions.
 
-* <<saved-objects-api-get, Get object API>>
+The following saved objects APIs are available: 
-* <<saved-objects-api-bulk-get, Bulk get objects API>>
+
-* <<saved-objects-api-find, Find objects API>>
+* <<saved-objects-api-get, Get object API>> to retrieve a single {kib} saved object by ID
-* <<saved-objects-api-create, Create saved object API>>
+
-* <<saved-objects-api-bulk-create, Bulk create saved objects API>>
+* <<saved-objects-api-bulk-get, Bulk get objects API>> to retrieve multiple {kib} saved objects by ID
-* <<saved-objects-api-update, Update object API>>
+
-* <<saved-objects-api-delete, Delete object API>>
+* <<saved-objects-api-find, Find objects API>> to retrieve a paginated set of {kib} saved objects by various conditions
-* <<saved-objects-api-export, Export objects API>>
+
-* <<saved-objects-api-import, Import objects API>>
+* <<saved-objects-api-create, Create saved object API>> to create {kib} saved objects
-* <<saved-objects-api-resolve-import-errors, Resolve import errors API>>
+
+* <<saved-objects-api-bulk-create, Bulk create saved objects API>> to create multiple {kib} saved objects
+
+* <<saved-objects-api-update, Update object API>> to update the attributes for existing {kib} saved objects
+
+* <<saved-objects-api-delete, Delete object API>> to remove {kib} saved objects
+
+* <<saved-objects-api-export, Export objects API>> to retrieve sets of saved objects that you want to import into {kib}
+
+* <<saved-objects-api-import, Import objects API>> to create sets of {kib} saved objects from a file created by the export API
+
+* <<saved-objects-api-resolve-import-errors, Resolve import errors API>> to resolve errors from the import API
 
 include::saved-objects/get.asciidoc[]
 include::saved-objects/bulk_get.asciidoc[]

docs/api/saved-objects/bulk_create.asciidoc

@@ -1,7 +1,7 @@
 [[saved-objects-api-bulk-create]]
 === Bulk create saved objects API
 ++++
-<titleabbrev>Bulk create objects</titleabbrev>
+<titleabbrev>Bulk create saved objects</titleabbrev>
 ++++
 
 experimental[] Create multiple {kib} saved objects.

docs/api/saved-objects/bulk_get.asciidoc

@@ -4,7 +4,7 @@
 <titleabbrev>Bulk get objects</titleabbrev>
 ++++
 
-experimental[] Retrieves multiple {kib} saved objects by ID.
+experimental[] Retrieve multiple {kib} saved objects by ID.
 
 [[saved-objects-api-bulk-get-request]]
 ==== Request

docs/api/saved-objects/create.asciidoc

@@ -1,10 +1,10 @@
 [[saved-objects-api-create]]
-=== Create saved object API
+=== Create saved objects API
 ++++
-<titleabbrev>Create object</titleabbrev>
+<titleabbrev>Create saved objects</titleabbrev>
 ++++
 
-experimental[] Create a {kib} saved object.
+experimental[] Create {kib} saved objects.
 
 [[saved-objects-api-create-request]]
 ==== Request

docs/api/saved-objects/delete.asciidoc

@@ -4,7 +4,7 @@
 <titleabbrev>Delete object</titleabbrev>
 ++++
 
-experimental[] Remove a {kib} saved object. 
+experimental[] Remove {kib} saved objects. 
 
 WARNING: Once you delete a saved object, _it cannot be recovered_.
 

docs/api/saved-objects/export.asciidoc

@@ -4,7 +4,7 @@
 <titleabbrev>Export objects</titleabbrev>
 ++++
 
-experimental[] Retrieve a set of saved objects that you want to import into {kib}.
+experimental[] Retrieve sets of saved objects that you want to import into {kib}.
 
 [[saved-objects-api-export-request]]
 ==== Request

docs/api/saved-objects/import.asciidoc

@@ -4,7 +4,7 @@
 <titleabbrev>Import objects</titleabbrev>
 ++++
 
-experimental[] Create a set of {kib} saved objects from a file created by the export API.
+experimental[] Create sets of {kib} saved objects from a file created by the export API.
 
 [[saved-objects-api-import-request]]
 ==== Request

docs/api/saved-objects/update.asciidoc

@@ -4,7 +4,7 @@
 <titleabbrev>Update object</titleabbrev>
 ++++
 
-experimental[] Update the attributes for an existing {kib} saved object.
+experimental[] Update the attributes for existing {kib} saved objects.
 
 [[saved-objects-api-update-request]]
 ==== Request

docs/api/spaces-management.asciidoc

@@ -1,16 +1,24 @@
 [role="xpack"]
 [[spaces-api]]
-== Kibana Spaces APIs
+== {kib} spaces APIs
 
 Manage your {kib} spaces.
 
-* <<spaces-api-post, Create space API>>
+The following {kib} spaces APIs are available:
-* <<spaces-api-put, Update space API>>
+
-* <<spaces-api-get, Get a space API>>
+* <<spaces-api-post, Create space API>> to create a {kib} space
-* <<spaces-api-get-all, Get all {kib} spaces API>>
+
-* <<spaces-api-delete, Delete space API>>
+* <<spaces-api-put, Update space API>> to update an existing {kib} space
-* <<spaces-api-copy-saved-objects, Copy saved objects to space API>>
+
-* <<spaces-api-resolve-copy-saved-objects-conflicts, Resolve copy saved objects to space conflicts API>>
+* <<spaces-api-get, Get a space API>> to retrieve a specified {kib} space
+
+* <<spaces-api-get-all, Get all {kib} spaces API>> to retrieve all {kib} spaces
+
+* <<spaces-api-delete, Delete space API>> to delete a {kib} space
+
+* <<spaces-api-copy-saved-objects, Copy saved objects to space API>> to copy saved objects between spaces
+
+* <<spaces-api-resolve-copy-saved-objects-conflicts, Resolve copy saved objects to space conflicts API>> to overwrite saved objects returned as errors from the copy saved objects to space API
 
 include::spaces-management/post.asciidoc[]
 include::spaces-management/put.asciidoc[]

docs/api/spaces-management/delete.asciidoc

@@ -4,7 +4,7 @@
 <titleabbrev>Delete space</titleabbrev>
 ++++
 
-Deletes a {kib} space.
+Delete a {kib} space.
 
 experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."]
 

docs/api/spaces-management/get.asciidoc

@@ -4,7 +4,7 @@
 <titleabbrev>Get space</titleabbrev>
 ++++
 
-Retrieves a specified {kib} space.
+Retrieve a specified {kib} space.
 
 experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."]
 

docs/api/spaces-management/get_all.asciidoc

@@ -4,7 +4,7 @@
 <titleabbrev>Get all spaces</titleabbrev>
 ++++
 
-Retrieves all {kib} spaces.
+Retrieve all {kib} spaces.
 
 experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."]
 

docs/api/spaces-management/post.asciidoc

@@ -4,7 +4,7 @@
 <titleabbrev>Create space</titleabbrev>
 ++++
 
-Creates a {kib} space.
+Create a {kib} space.
 
 experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."]
 

docs/api/spaces-management/put.asciidoc

@@ -4,7 +4,7 @@
 <titleabbrev>Update space</titleabbrev>
 ++++
 
-Updates an existing {kib} space.
+Update an existing {kib} space.
 
 experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."]
 

docs/api/spaces-management/resolve_copy_saved_objects_conflicts.asciidoc

@@ -5,7 +5,7 @@
 <titleabbrev>Resolve copy to space conflicts</titleabbrev>
 ++++
 
-Overwrites specific saved objects that were returned as errors from the <<spaces-api-copy-saved-objects, Copy Saved Objects to Space API>>.
+Overwrite specific saved objects that were returned as errors from the <<spaces-api-copy-saved-objects, Copy Saved Objects to Space API>>.
 
 experimental["The underlying Spaces concepts are stable, but the APIs for managing Spaces are experimental."]
 

docs/api/upgrade-assistant.asciidoc

@@ -4,10 +4,15 @@
 
 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.
 
-* <<upgrade-assistant-api-status, Upgrade readiness status API>>
+The following upgrade assistant APIs are available:
-* <<start-resume-reindex, Start or resume reindex API>>
+
-* <<check-reindex-status, Check reindex status API>>
+* <<upgrade-assistant-api-status, Upgrade readiness status API>> to check the status of your cluster
-* <<cancel-reindex, Cancel reindex API>>
+
+* <<start-resume-reindex, Start or resume reindex API>> to start a new reindex or resume a paused reindex
+
+* <<check-reindex-status, Check reindex status API>> to check the status of the reindex operation
+
+* <<cancel-reindex, Cancel reindex API>> to cancel reindexes that are waiting for the Elasticsearch reindex task to complete
 
 include::upgrade-assistant/status.asciidoc[]
 include::upgrade-assistant/reindexing.asciidoc[]

docs/api/url-shortening.asciidoc

@@ -1,11 +1,57 @@
 [[url-shortening-api]]
-== URL shortening API
+=== Shorten URL API
+++++
+<titleabbrev>Shorten URL</titleabbrev>
+++++
 
-{kib} URLs contain the state of the application, which makes them long and cumbersome.
+experimental[] Convert a {kib} URL into a token. {kib} URLs contain the state of the application, which makes them long and cumbersome.
 Internet Explorer has URL length restrictions, and some wiki and markup parsers don't do well with the full-length version of the {kib} URL.
 
 Short URLs are designed to make sharing {kib} URLs easier.
 
-* <<shorten-url-api, Shorten URL API>>
+[[url-shortening-api-request]]
+==== Request
 
-include::url_shortening/shorten_url.asciidoc[]
+`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`.
+
+[[url-shortening-api-response-body]]
+==== Response body
+
+urlId:: A top level property that contains the shortened URL token for the provided request body.
+
+[[url-shortening-api-codes]]
+==== Response code
+
+`200`::
+  Indicates a successful call.
+
+[[url-shortening-api-example]]  
+==== Example
+
+[source,js]
+--------------------------------------------------
+POST 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:
+
+[source,js]
+--------------------------------------------------
+{
+  "urlId": "f73b295ff92718b26bc94edac766d8e3"
+}
+--------------------------------------------------
+
+For easy sharing, construct the shortened {kib} URL:
+
+`http://localhost:5601/goto/f73b295ff92718b26bc94edac766d8e3`

docs/api/url_shortening/shorten_url.asciidoc

@@ -1,55 +0,0 @@
-[[shorten-url-api]]
-=== Shorten URL API
-++++
-<titleabbrev>Shorten URL</titleabbrev>
-++++
-
-experimental[] Convert a {kib} URL into a token.
-
-[[url-shortening-api-request]]
-==== Request
-
-`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`.
-
-[[url-shortening-api-response-body]]
-==== Response body
-
-urlId:: A top level property that contains the shortened URL token for the provided request body.
-
-[[url-shortening-api-codes]]
-==== Response code
-
-`200`::
-  Indicates a successful call.
-
-[[url-shortening-api-example]]  
-==== Example
-
-[source,js]
---------------------------------------------------
-POST 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:
-
-[source,js]
---------------------------------------------------
-{
-  "urlId": "f73b295ff92718b26bc94edac766d8e3"
-}
---------------------------------------------------
-
-For easy sharing, construct the shortened {kib} URL:
-
-`http://localhost:5601/goto/f73b295ff92718b26bc94edac766d8e3`
-

docs/api/using-api.asciidoc

@@ -0,0 +1,46 @@
+[[using-api]]
+== Using the APIs
+
+Interact with the {kib} APIs through the `curl` command and HTTP and HTTPs protocols. 
+
+It is recommended that you use HTTPs on port 5601 because it is more secure.
+
+NOTE: The {kib} Console supports only Elasticsearch APIs. You are unable to interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to <<console-kibana,Console>>.
+
+[float]
+[[api-authentication]]
+=== Authentication
+{kib} supports token-based authentication with the same username and password that you use to log into the {kib} Console.
+
+[float]
+[[api-calls]]
+=== API calls
+API calls are stateless. Each request that you make happens in isolation from other calls and must include all of the necessary information for {kib} to fulfill the request. API requests return JSON output, which is a format that is machine-readable and works well for automation.
+
+Calls to the API endpoints require different operations. To interact with the {kib} APIs, use the following operations:
+
+* *GET* - Fetches the information.
+
+* *POST* - Adds new information.
+
+* *PUT* - Updates the existing information.
+
+* *DELETE* - Removes the information.
+
+For example, the following `curl` command exports a dashboard:
+
+[source,sh]
+--
+curl -X POST -u $USER:$PASSWORD "localhost:5601/api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c"
+--
+
+The following {kib} APIs are available:
+
+* <<features-api-get, Get features API>>
+* <<spaces-api, Kibana spaces API>>
+* <<role-management-api, Kibana role management APIs>>
+* <<saved-objects-api, Saved objects APIs>>
+* <<dashboard-api, Import and export dashboards APIs>>
+* <<logstash-configuration-management-api, Logstash configuration mangaement APIs>>
+* <<url-shortening-api, Shorten URL API>>
+* <<upgrade-assistant-api, Upgrade assistant APIs>>

docs/dev-tools/console/console.asciidoc

@@ -12,6 +12,8 @@ To get started, go to *Dev Tools > Console*.
 [role="screenshot"]
 image::dev-tools/console/images/console.png["Console"]
 
+NOTE: You are unable to interact with the REST API of {kib} with the Console.
+
 [float]
 [[console-api]]
 === Write requests

docs/user/api.asciidoc

@@ -8,7 +8,7 @@ integration with {kib}, or automating certain aspects of configuring and
 deploying {kib}.
 
 Each API is experimental and can include breaking changes in any version of 
-{kib}, or might have been entirely removed from {kib}.
+{kib}, or might be entirely removed from {kib}.
 
 ////
 Each API has one of the following labels:
@@ -29,25 +29,14 @@ entirely.
 If a label is missing from an API, it is considered `experimental`.
 ////
 
-NOTE: You cannot access the APIs via the Console in {kib}.
-
-[float]
-== APIs
-* <<features-api>>
-* <<spaces-api>>
-* <<role-management-api>>
-* <<saved-objects-api>>
-* <<dashboard-import-api>>
-* <<logstash-configuration-management-api>>
-* <<url-shortening-api>>
-* <<upgrade-assistant-api>>
 --
 
+include::{kib-repo-dir}/api/using-api.asciidoc[]
 include::{kib-repo-dir}/api/features.asciidoc[]
 include::{kib-repo-dir}/api/spaces-management.asciidoc[]
 include::{kib-repo-dir}/api/role-management.asciidoc[]
 include::{kib-repo-dir}/api/saved-objects.asciidoc[]
-include::{kib-repo-dir}/api/dashboard-import.asciidoc[]
+include::{kib-repo-dir}/api/dashboard-api.asciidoc[]
 include::{kib-repo-dir}/api/logstash-configuration-management.asciidoc[]
 include::{kib-repo-dir}/api/url-shortening.asciidoc[]
 include::{kib-repo-dir}/api/upgrade-assistant.asciidoc[]