diff --git a/doc/source/cells.rst b/doc/source/cells.rst
index c1b572a654..27497a5a89 100644
--- a/doc/source/cells.rst
+++ b/doc/source/cells.rst
@@ -386,7 +386,8 @@ database yet. This will set up a single cell Nova deployment.
    configuration file if not specified on the command line.
 
 6. Configure and start your compute hosts. Before step 7, make sure you have
-   compute hosts in the database by running ``nova hypervisor-list``.
+   compute hosts in the database by running
+   ``nova service-list --binary nova-compute``.
 
 7. Run the ``discover_hosts`` command to map compute hosts to the single cell::
 
diff --git a/doc/source/man/nova-manage.rst b/doc/source/man/nova-manage.rst
index 50c0439dd3..afcdd6f4b0 100644
--- a/doc/source/man/nova-manage.rst
+++ b/doc/source/man/nova-manage.rst
@@ -148,7 +148,7 @@ Nova Cells v2
     any hosts which are not currently mapped. If a host is already mapped
     nothing will be done. You need to re-run this command each time you add
     more compute hosts to a cell (otherwise the scheduler will never place
-    instances there).
+    instances there and the API will not list the new hosts).
 
 ``nova-manage cell_v2 list_cells [--verbose]``
 
diff --git a/releasenotes/notes/pike-multicell-api-ae4fbebd711165ce.yaml b/releasenotes/notes/pike-multicell-api-ae4fbebd711165ce.yaml
new file mode 100644
index 0000000000..92ff89f770
--- /dev/null
+++ b/releasenotes/notes/pike-multicell-api-ae4fbebd711165ce.yaml
@@ -0,0 +1,24 @@
+---
+upgrade:
+  - |
+    Parts of the compute REST API are now relying on getting information from
+    cells via their mappings in the ``nova_api`` database. This is to support
+    multiple cells. For example, when listing compute hosts or services, all
+    cells will be iterated in the API and the results will be returned.
+
+    This change can have impacts, however, to deployment tooling that relies on
+    parts of the API, like listing compute hosts, `before` the compute hosts
+    are mapped using the ``nova-manage cell_v2 discover_hosts`` command.
+
+    If you were using ``nova hypervisor-list`` after starting new nova-compute
+    services to tell when to run ``nova-manage cell_v2 discover_hosts``, you
+    should change your tooling to instead use one of the following commands::
+
+      nova service-list --binary nova-compute [--host <hostname>]
+
+      openstack compute service list --service nova-compute [--host <host>]
+
+    As a reminder, there is also the
+    ``[scheduler]/discover_hosts_in_cells_interval`` configuration option which
+    can be used to automatically discover hosts from the nova-scheduler
+    service.
\ No newline at end of file