diff --git a/placement-api-ref/source/allocations.inc b/placement-api-ref/source/allocations.inc
new file mode 100644
index 000000000000..0987250f6f92
--- /dev/null
+++ b/placement-api-ref/source/allocations.inc
@@ -0,0 +1,106 @@
+===========
+Allocations
+===========
+
+Allocations are records representing resources that have been assigned
+and used by some consumer of that resource. They indicate the amount
+of a particular resource that has been allocated to a given consumer
+of that resource from a particular resource provider.
+
+List allocations
+================
+
+List all allocation records for the consumer identified by
+`{consumer_uuid}` on all the resource providers it is consuming.
+
+.. rest_method:: GET /allocations/{consumer_uuid}
+
+Normal Response Codes: 200
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - consumer_uuid: consumer_uuid
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - allocations: allocations_by_resource_provider
+  - generation: resource_provider_generation
+  - resources: resources
+
+Response Example
+----------------
+
+.. literalinclude:: get-allocations.json
+   :language: javascript
+
+Update allocations
+==================
+
+Create or update one or more allocation records representing the consumption of
+one or more classes of resources from one or more resource providers by
+the consumer identified by `{consumer_uuid}`.
+If allocations already exist for this consumer, they are replaced.
+
+.. rest_method:: PUT /allocations/{consumer_uuid}
+
+Normal Response Codes: 204
+
+Error response codes: badRequest(400), itemNotFound(404), conflict(409)
+
+* `409 Conflict` if there is no available inventory in any of the
+  resource providers for any specified resource classes or inventories
+  are updated by another thread while attempting the operation.
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - consumer_uuid: consumer_uuid
+  - allocations: allocations_array
+  - resources: resources
+  - resource_provider: resource_provider_object
+  - uuid: resource_provider_uuid
+  - project_id: project_id_body
+  - user_id: user_id_body
+
+Request example
+---------------
+
+.. literalinclude:: update-allocations-request.json
+   :language: javascript
+
+Response
+--------
+
+No body content is returned on a successful PUT.
+
+Delete allocations
+==================
+
+Delete all allocation records for the consumer identified by
+`{consumer_uuid}` on all resource providers it is consuming.
+
+.. rest_method:: DELETE /allocations/{consumer_uuid}
+
+Normal Response Codes: 204
+
+Error response codes: itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - consumer_uuid: consumer_uuid
+
+Response
+--------
+
+No body content is returned on a successful DELETE.
diff --git a/placement-api-ref/source/get-allocations.json b/placement-api-ref/source/get-allocations.json
new file mode 100644
index 000000000000..3d12298b90b0
--- /dev/null
+++ b/placement-api-ref/source/get-allocations.json
@@ -0,0 +1,17 @@
+{
+    "allocations": {
+        "92637880-2d79-43c6-afab-d860886c6391": {
+            "generation": 2,
+            "resources": {
+                "DISK_GB": 5
+            }
+        },
+        "ba8e1ef8-7fa3-41a4-9bb4-d7cb2019899b": {
+            "generation": 8,
+            "resources": {
+                "MEMORY_MB": 512,
+                "VCPU": 2
+            }
+        }
+    }
+}
diff --git a/placement-api-ref/source/index.rst b/placement-api-ref/source/index.rst
index 3773477fa4d2..277d5d2639b0 100644
--- a/placement-api-ref/source/index.rst
+++ b/placement-api-ref/source/index.rst
@@ -22,3 +22,4 @@ Openstack Placement API concepts, please refer to the
 .. include:: aggregates.inc
 .. include:: traits.inc
 .. include:: resource_provider_traits.inc
+.. include:: allocations.inc
diff --git a/placement-api-ref/source/parameters.yaml b/placement-api-ref/source/parameters.yaml
index 603fb41de74a..eb0b0a9fa57f 100644
--- a/placement-api-ref/source/parameters.yaml
+++ b/placement-api-ref/source/parameters.yaml
@@ -1,4 +1,10 @@
 # variables in path
+consumer_uuid:
+  type: string
+  in: path
+  required: true
+  description: >
+    The uuid of a consumer.
 resource_class_path: &resource_class_path
   type: string
   in: path
@@ -27,6 +33,12 @@ member_of:
     A comma-separated list of strings representing aggregate uuids.
     The returned resource providers must be associated with at
     least one of the aggregates identified by uuid.
+project_id: &project_id
+  type: string
+  in: query
+  required: true
+  description: >
+    The uuid of a project.
 resource_provider_name_query:
   type: string
   in: query
@@ -67,6 +79,12 @@ trait_name_query:
 
     `in` operator filters the traits whose name is in the specified list, e.g.
     name=in:HW_CPU_X86_AVX,HW_CPU_X86_SSE,HW_CPU_X86_INVALID_FEATURE.
+user_id: &user_id
+  type: string
+  in: query
+  required: false
+  description: >
+    The uuid of a user.
 
 # variables in body
 aggregates:
@@ -92,6 +110,18 @@ allocation_ratio: &allocation_ratio
 allocation_ratio_opt:
   <<: *allocation_ratio
   required: false
+allocations_array:
+  type: array
+  in: body
+  required: true
+  description: >
+    A list of dictionaries.
+allocations_by_resource_provider:
+  type: object
+  in: body
+  required: true
+  description: >
+    A dictionary of allocations keyed by resource provider uuid.
 inventories:
   type: object
   in: body
@@ -116,6 +146,10 @@ min_unit: &min_unit
 min_unit_opt:
   <<: *min_unit
   required: false
+project_id_body:
+  <<: *project_id
+  in: body
+  min_version: 1.8
 reserved: &reserved
   type: integer
   in: body
@@ -162,6 +196,12 @@ resource_provider_name:
   required: true
   description: >
     The name of one resource provider.
+resource_provider_object:
+  type: object
+  in: body
+  required: true
+  description: >
+    A dictionary contains uuid of the resource provider.
 resource_provider_uuid:
   <<: *resource_provider_uuid_path
   in: body
@@ -175,6 +215,12 @@ resource_providers:
   required: true
   description: >
     A list of ``resource_provider`` objects.
+resources:
+  type: object
+  in: body
+  required: true
+  description: >
+    A dictionary of resource records keyed by resource class name.
 step_size: &step_size
   type: integer
   in: body
@@ -198,6 +244,11 @@ traits:
   required: true
   description: >
     A list of traits.
+user_id_body:
+  <<: *user_id
+  in: body
+  required: true
+  min_version: 1.8
 version_id:
   type: string
   in: body
diff --git a/placement-api-ref/source/update-allocations-request.json b/placement-api-ref/source/update-allocations-request.json
new file mode 100644
index 000000000000..49d7eb39fd86
--- /dev/null
+++ b/placement-api-ref/source/update-allocations-request.json
@@ -0,0 +1,23 @@
+{
+    "allocations": [
+        {
+            "resource_provider": {
+                "uuid": "844ac34d-620e-474c-833c-4c9921251353"
+            },
+            "resources": {
+                "MEMORY_MB": 512,
+                "VCPU": 2
+            }
+        },
+        {
+            "resource_provider": {
+                "uuid": "92637880-2d79-43c6-afab-d860886c6391"
+            },
+            "resources": {
+                "DISK_GB": 5
+            }
+        }
+    ],
+    "project_id": "6e3b2ce9-9175-4830-a862-b9de690bdceb",
+    "user_id": "81c516e3-5e0e-4dcb-9a38-4473d229a950"
+}