diff --git a/api-ref/source/flavors.inc b/api-ref/source/flavors.inc
new file mode 100644
index 000000000..f885edbd1
--- /dev/null
+++ b/api-ref/source/flavors.inc
@@ -0,0 +1,205 @@
+================
+Flavors (flavors)
+================
+Queue flavors allow users to have different types of queues based on the
+storage capabilities. By using flavors, it's possible to allow consumers of the
+service to choos between durable storage, fast storage, etc. Flavors must be
+created by service administrators and they rely on the existence of pools.
+
+List flavors
+============
+
+.. rest_method::  GET /v2/flavors
+
+Lists flavors.
+
+This operation lists flavors for the project. The flavors are sorted
+alphabetically by name.
+
+
+Normal response codes: 200
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+
+Query Parameters
+-----------------
+
+.. rest_parameters:: parameters.yaml
+
+  - limit: limit
+  - marker: marker
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - flavors: flavors
+  - links: flavor_links
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/flavor-list-response.json
+   :language: javascript
+
+
+Create flavor
+=============
+
+.. rest_method::  PUT /v2/flavors/{flavor_name}
+
+Creates a flavor.
+
+This operation creates a new flavor.
+
+``flaovr_name`` is the name that you give to the flavor. The name must not
+exceed 64 bytes in length, and it is limited to US-ASCII letters, digits,
+underscores, and hyphens.
+
+
+Normal response codes: 201
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- Forbidden (403)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - flavor_name: flavor_name_path
+  - pool_group: flavor_pool_group
+
+Request Example
+---------------
+
+.. literalinclude:: samples/flavor-create-request.json
+   :language: javascript
+
+
+This operation does not return a response body.
+
+
+Update flavor
+=============
+
+.. rest_method::  PATCH /v2/flavors/{flavor_name}
+
+Updates a flavor.
+
+Normal response codes: 200
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- Forbidden (403)
+- Not Found (404)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - flaovr_name: flavor_name_path
+  - pool_group: flavor_pool_group
+
+
+Request Example
+---------------
+
+.. literalinclude:: samples/flavor-update-request.json
+   :language: javascript
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/flavor-update-response.json
+   :language: javascript
+
+
+Show flavor details
+===================
+
+.. rest_method::  GET /v2/flavors/{flavor_name}
+
+Shows details for a flavor.
+
+Normal response codes: 200
+
+Error response codes:
+
+- BadRequest (400)
+- Unauthorized (401)
+- Forbidden (403)
+- Not Found (404)
+- ServiceUnavailable (503)
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - flavor_name: flavor_name_path
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - name: flavor_name
+  - capabilities: capabilities
+  - pool_group: flavor_pool_group
+  - href: flavor_href
+
+Response Example
+----------------
+
+.. literalinclude:: samples/flavor-show-response.json
+   :language: javascript
+
+
+Delete flavor
+=============
+
+.. rest_method::  DELETE /v2/flavors/{flavor_name}
+
+Deletes the specified flavor.
+
+This operation immediately deletes a flavor.
+
+``flavor_name`` is the name that you give to the flavor. The name must not
+exceed 64 bytes in length, and it is limited to US-ASCII letters, digits,
+underscores, and hyphens.
+
+
+Normal response codes: 204
+
+Error response codes:
+
+- Unauthorized (401)
+- Forbidden (403)
+- ServiceUnavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - flavor_name: flavor_name_path
+
+This operation does not accept a request body and does not return a response
+body.
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index 324ef8d8b..3c3f87399 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -24,3 +24,4 @@ Messaging Service API v2 (CURRENT)
 .. include:: subscription.inc
 .. include:: health.inc
 .. include:: pools.inc
+.. include:: flavors.inc
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 6c44516c2..5760cb687 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -42,6 +42,13 @@ pool_name_path:
   description:
     The name of the pool.
 
+flavor_name_path:
+  type: string
+  in: path
+  required: True
+  description:
+    The name of the flavor.
+
 #### variables in query ######################################################
 
 limit:
@@ -198,6 +205,14 @@ pool_options:
     driver implementations. The value must be a dict and valid key-value come
     from the registered options for a given storage backend.
 
+flavor_pool_group:
+  type: string
+  in: body
+  required: true
+  description: |
+    The ``pool_group`` attribute specifies the name of the pool group
+    this flavor sits on top of.
+
 #### variables in response ###################################################
 
 versions:
@@ -383,3 +398,37 @@ pool_links:
   description: |
     Links related to the pools. This is a list of dictionaries, each including
     keys ``href`` and ``rel``.
+
+flavors:
+  type: list
+  in: body
+  description: |
+    A list of the flaovrs.
+
+flavor_links:
+  type: array
+  in: body
+  required: true
+  description: |
+    Links related to the flavors. This is a list of dictionaries, each including
+    keys ``href`` and ``rel``.
+
+flavor_name:
+  type: string
+  in: body
+  required: true
+  description: |
+    The name of the flavor.
+
+flavor_href:
+  type: string
+  in: body
+  description: |
+    The url of the flavor.
+
+capabilities:
+  type: list
+  in: body
+  description: |
+    Capabilities describe what this flavor is capable of base on the storage
+    capabilities. They are used to inform the final user such capabilities.
diff --git a/api-ref/source/samples/flavor-create-request.json b/api-ref/source/samples/flavor-create-request.json
new file mode 100644
index 000000000..d2da2d88b
--- /dev/null
+++ b/api-ref/source/samples/flavor-create-request.json
@@ -0,0 +1,3 @@
+{
+    "pool_group": "testgroup"
+}
\ No newline at end of file
diff --git a/api-ref/source/samples/flavor-list-response.json b/api-ref/source/samples/flavor-list-response.json
new file mode 100644
index 000000000..f890dd3d2
--- /dev/null
+++ b/api-ref/source/samples/flavor-list-response.json
@@ -0,0 +1,22 @@
+{
+  "flavors": [
+    {
+      "href": "/v2/flavors/test_flavor1",
+      "pool_group": "testgroup",
+      "name": "test_flavor1",
+      "pool": "testgroup"
+    },
+    {
+      "href": "/v2/flavors/test_flavor2",
+      "pool_group": "testgroup",
+      "name": "test_flavor2",
+      "pool": "testgroup"
+    }
+  ],
+  "links": [
+    {
+      "href": "/v2/flavors?marker=test_flavor2",
+      "rel": "next"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/api-ref/source/samples/flavor-show-response.json b/api-ref/source/samples/flavor-show-response.json
new file mode 100644
index 000000000..edba44fd8
--- /dev/null
+++ b/api-ref/source/samples/flavor-show-response.json
@@ -0,0 +1,12 @@
+{
+  "href": "/v2/flavors/testflavor",
+  "capabilities": [
+    "FIFO",
+    "CLAIMS",
+    "DURABILITY",
+    "AOD",
+    "HIGH_THROUGHPUT"
+  ],
+  "pool_group": "testgroup",
+  "name": "testflavor"
+}
\ No newline at end of file
diff --git a/api-ref/source/samples/flavor-update-request.json b/api-ref/source/samples/flavor-update-request.json
new file mode 100644
index 000000000..d2da2d88b
--- /dev/null
+++ b/api-ref/source/samples/flavor-update-request.json
@@ -0,0 +1,3 @@
+{
+    "pool_group": "testgroup"
+}
\ No newline at end of file
diff --git a/api-ref/source/samples/flavor-update-response.json b/api-ref/source/samples/flavor-update-response.json
new file mode 100644
index 000000000..d8360e02a
--- /dev/null
+++ b/api-ref/source/samples/flavor-update-response.json
@@ -0,0 +1,12 @@
+{
+  "href": "/v2/flavors/testflavor",
+  "pool_group": "testgroup",
+  "name": "testflavor",
+  "capabilities": [
+    "FIFO",
+    "CLAIMS",
+    "DURABILITY",
+    "AOD",
+    "HIGH_THROUGHPUT"
+  ]
+}
\ No newline at end of file