diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index d7da32349a..85ff0a954a 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -41,7 +41,6 @@ the `API guide <http://developer.openstack.org/api-guide/compute/index.html>`_.
 .. include:: os-aggregates.inc
 .. include:: os-assisted-volume-snapshots.inc
 .. include:: os-availability-zone.inc
-.. include:: os-cells.inc
 .. include:: os-consoles.inc
 .. include:: os-hypervisors.inc
 .. include:: os-instance-usage-audit-log.inc
@@ -54,6 +53,14 @@ the `API guide <http://developer.openstack.org/api-guide/compute/index.html>`_.
 .. include:: os-services.inc
 .. include:: os-simple-tenant-usage.inc
 .. include:: os-server-external-events.inc
+
+===============
+Deprecated APIs
+===============
+
+This section contains references for APIs which are deprecated and usually
+limited to some maximum microversion.
+
 .. include:: extensions.inc
 .. include:: os-networks.inc
 .. include:: os-volumes.inc
@@ -66,6 +73,7 @@ the `API guide <http://developer.openstack.org/api-guide/compute/index.html>`_.
 .. include:: os-security-group-default-rules.inc
 .. include:: os-security-group-rules.inc
 .. include:: os-hosts.inc
+.. include:: os-cells.inc
 
 =============
 Obsolete APIs
diff --git a/api-ref/source/os-cells.inc b/api-ref/source/os-cells.inc
index cbc20ad42b..de0d610f6a 100644
--- a/api-ref/source/os-cells.inc
+++ b/api-ref/source/os-cells.inc
@@ -11,8 +11,8 @@
 Adds neighbor cells, lists neighbor cells, and shows the capabilities of
 the local cell. By default, only administrators can manage cells.
 
-.. note:: These APIs refer to a Cells v1 deployment which is optional and not
-  recommended for new deployments of Nova. These are not used with Cells v2
+.. warning:: These APIs refer to a Cells v1 deployment which was deprecated
+  in the 16.0.0 Pike release. These are not used with Cells v2
   which is required beginning with the 15.0.0 Ocata release where all Nova
   deployments consist of at least one Cells v2 cell.
 
@@ -37,8 +37,6 @@ Request
   - limit: limit_simple
   - offset: offset_simple
 
-.. TODO(cdent): How do we indicate optionality of a URI parameter?
-
 Response
 --------
 
@@ -59,10 +57,6 @@ Normal response code: 200
 Error response codes: badRequest(400), unauthorized(401), forbidden(403),
 NotImplemented(501)
 
-.. TODO(cdent): need to figure out body stuff for request and response
-
-.. TODO(cdent): need a sample
-
 Capacities
 ==========
 
@@ -73,8 +67,6 @@ Retrieve capacities.
 Error response codes: badRequest(400), unauthorized(401), forbidden(403),
 NotImplemented(501)
 
-.. TODO(cdent): Need to do more digging, no idea.
-
 List Cells With Details
 =======================
 
@@ -95,17 +87,6 @@ Request
   - limit: limit_simple
   - offset: offset_simple
 
-Response
---------
-
-**Example List Cells With Details: JSON response**
-
-.. TODO(cdent): This sample was initially list with an empty list of cells.
-   The newly listed sample does not yet exist.
-
-.. TODO(cdent):  literal-include: ../../doc/api_samples/os-cells/cells-list-details-resp.json
-   :language: javascript
-
 Info For This Cell
 ==================
 
@@ -118,8 +99,6 @@ Normal response code: 200
 Error response codes: badRequest(400), unauthorized(401), forbidden(403),
 NotImplemented(501)
 
-.. TODO(cdent): this is weird, data is structured entirely differently.
-
 Show Cell Data
 ==============
 
@@ -160,8 +139,6 @@ Normal response code: 200
 Error response codes: badRequest(400), unauthorized(401), forbidden(403),
 itemNotFound(404), NotImplemented(501)
 
-.. TODO(cdent): Figure out what's going on here.
-
 Delete a Cell
 =============
 
@@ -181,8 +158,6 @@ Show Cell Capacities
 
 Shows capacities for a cell.
 
-.. TODO(cdent): What's a capacities.
-
 Normal response codes: 200,501
 
 Error response codes: badRequest(400), unauthorized(401), forbidden(403),