diff --git a/api-ref/source/alarms.inc b/api-ref/source/alarms.inc
new file mode 100755
index 0000000000..136685f3bb
--- /dev/null
+++ b/api-ref/source/alarms.inc
@@ -0,0 +1,333 @@
+.. -*- rst -*-
+
+======
+Alarms
+======
+
+Lists, creates, gets details for, updates, and deletes alarms.
+
+
+Show alarm details
+==================
+
+.. rest_method::  GET /v2/alarms/{alarm_id}
+
+Shows details for an alarm, by alarm ID.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - alarm_id: alarm_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - alarm_actions: alarm_actions
+   - alarm_id: alarm_id
+   - combination_rule: combination_rule
+   - description: description
+   - enabled: enabled
+   - insufficient_data_actions: insufficient_data_actions
+   - timestamp: timestamp
+   - name: name
+   - ok_actions: ok_actions
+   - project_id: project_id
+   - state_timestamp: state_timestamp
+   - threshold_rule: threshold_rule
+   - repeat_actions: repeat_actions
+   - state: state
+   - type: type
+   - user_id: user_id
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/alarm-show-response.json
+   :language: javascript
+
+
+
+
+Update alarm
+============
+
+.. rest_method::  PUT /v2/alarms/{alarm_id}
+
+Updates an alarm.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - alarm_id: alarm_id
+   - data: data
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - alarm_actions: alarm_actions
+   - ok_actions: ok_actions
+   - description: description
+   - timestamp: timestamp
+   - enabled: enabled
+   - combination_rule: combination_rule
+   - state_timestamp: state_timestamp
+   - threshold_rule: threshold_rule
+   - alarm_id: alarm_id
+   - state: state
+   - insufficient_data_actions: insufficient_data_actions
+   - repeat_actions: repeat_actions
+   - user_id: user_id
+   - project_id: project_id
+   - type: type
+   - name: name
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/alarm-show-response.json
+   :language: javascript
+
+
+
+
+Delete alarm
+============
+
+.. rest_method::  DELETE /v2/alarms/{alarm_id}
+
+Deletes an alarm, by alarm ID.
+
+Error response codes:204
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - alarm_id: alarm_id
+
+
+
+
+
+
+Update alarm state
+==================
+
+.. rest_method::  PUT /v2/alarms/{alarm_id}/state
+
+Sets the state of an alarm.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - alarm_id: alarm_id
+   - state: state
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude::
+   :language: javascript
+
+
+
+
+Show alarm state
+================
+
+.. rest_method::  GET /v2/alarms/{alarm_id}/state
+
+Shows the state for an alarm, by alarm ID.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - alarm_id: alarm_id
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude::
+   :language: javascript
+
+
+
+
+List alarms
+===========
+
+.. rest_method::  GET /v2/alarms
+
+Lists alarms, based on a query.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - q: q
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - alarm_actions: alarm_actions
+   - ok_actions: ok_actions
+   - description: description
+   - timestamp: timestamp
+   - enabled: enabled
+   - combination_rule: combination_rule
+   - state_timestamp: state_timestamp
+   - threshold_rule: threshold_rule
+   - alarm_id: alarm_id
+   - state: state
+   - insufficient_data_actions: insufficient_data_actions
+   - repeat_actions: repeat_actions
+   - user_id: user_id
+   - project_id: project_id
+   - type: type
+   - name: name
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/alarms-list-response.json
+   :language: javascript
+
+
+
+
+Create alarm
+============
+
+.. rest_method::  POST /v2/alarms
+
+Creates an alarm.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - data: data
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - alarm_actions: alarm_actions
+   - ok_actions: ok_actions
+   - description: description
+   - timestamp: timestamp
+   - enabled: enabled
+   - combination_rule: combination_rule
+   - state_timestamp: state_timestamp
+   - threshold_rule: threshold_rule
+   - alarm_id: alarm_id
+   - state: state
+   - insufficient_data_actions: insufficient_data_actions
+   - repeat_actions: repeat_actions
+   - user_id: user_id
+   - project_id: project_id
+   - type: type
+   - name: name
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/alarm-show-response.json
+   :language: javascript
+
+
+
+
+Show alarm history
+==================
+
+.. rest_method::  GET /v2/alarms/{alarm_id}/history
+
+Assembles and shows the history for an alarm, by alarm ID.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - alarm_id: alarm_id
+   - q: q
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude::
+   :language: javascript
diff --git a/api-ref/source/capabilities.inc b/api-ref/source/capabilities.inc
new file mode 100755
index 0000000000..e3461b28a6
--- /dev/null
+++ b/api-ref/source/capabilities.inc
@@ -0,0 +1,92 @@
+.. -*- rst -*-
+
+============
+Capabilities
+============
+
+Gets information for API and storage capabilities.
+
+The Telemetry service enables you to store samples, events, and
+alarm definitions in supported database back ends. The
+``capabilities`` resource enables you to list the capabilities that
+a database supports.
+
+The ``capabilities`` resource returns a flattened dictionary of
+capability properties, each with an associated boolean value. A
+value of ``true`` indicates that the corresponding capability is
+available in the back end.
+
+You can optionally configure separate database back ends for
+samples, events, and alarms definitions. The ``capabilities``
+response shows a value of ``true`` to indicate that the definitions
+database for samples, events, or alarms is ready to use in a
+production environment.
+
+
+List capabilities
+=================
+
+.. rest_method::  GET /v2/capabilities
+
+A representation of the API and storage capabilities. Usually, the storage driver imposes constraints.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - statistics:query:complex: statistics:query:complex
+   - alarms:history:query:simple: alarms:history:query:simple
+   - meters:query:metadata: meters:query:metadata
+   - alarms:query:simple: alarms:query:simple
+   - resources:query:simple: resources:query:simple
+   - api: api
+   - statistics:aggregation:selectable:quartile: statistics:aggregation:selectable:quartile
+   - statistics:query:simple: statistics:query:simple
+   - statistics:aggregation:selectable:count: statistics:aggregation:selectable:count
+   - statistics:aggregation:selectable:min: statistics:aggregation:selectable:min
+   - statistics:aggregation:selectable:sum: statistics:aggregation:selectable:sum
+   - storage: storage
+   - alarm_storage: alarm_storage
+   - statistics:aggregation:selectable:avg: statistics:aggregation:selectable:avg
+   - meters:query:complex: meters:query:complex
+   - statistics:groupby: statistics:groupby
+   - alarms:history:query:complex: alarms:history:query:complex
+   - meters:query:simple: meters:query:simple
+   - samples:query:metadata: samples:query:metadata
+   - statistics:query:metadata: statistics:query:metadata
+   - storage:production_ready: storage:production_ready
+   - samples:query:simple: samples:query:simple
+   - resources:query:metadata: resources:query:metadata
+   - statistics:aggregation:selectable:max: statistics:aggregation:selectable:max
+   - samples:query:complex: samples:query:complex
+   - statistics:aggregation:standard: statistics:aggregation:standard
+   - events:query:simple: events:query:simple
+   - statistics:aggregation:selectable:stddev: statistics:aggregation:selectable:stddev
+   - alarms:query:complex: alarms:query:complex
+   - statistics:aggregation:selectable:cardinality: statistics:aggregation:selectable:cardinality
+   - event_storage: event_storage
+   - resources:query:complex: resources:query:complex
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/capabilities-list-response.json
+   :language: javascript
+
+
+
diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py
new file mode 100644
index 0000000000..2242305f7e
--- /dev/null
+++ b/api-ref/source/conf.py
@@ -0,0 +1,258 @@
+# -*- coding: utf-8 -*-
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+# nova documentation build configuration file, created by
+# sphinx-quickstart on Sat May  1 15:17:47 2010.
+#
+# This file is execfile()d with the current directory set to
+# its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import os
+import subprocess
+import sys
+import warnings
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('../../'))
+sys.path.insert(0, os.path.abspath('../'))
+sys.path.insert(0, os.path.abspath('./'))
+
+# -- General configuration ----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+
+extensions = [
+    'os_api_ref',
+    'oslosphinx',
+]
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#
+# source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Compute API Reference'
+copyright = u'2010-present, OpenStack Foundation'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+from ceilometer.version import version_info as ceilometer_version
+# The full version, including alpha/beta/rc tags.
+release = ceilometer_version.version_string_with_vcs()
+# The short X.Y version.
+version = ceilometer_version.canonical_version_string()
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+# today = ''
+# Else, today_fmt is used as the format for a strftime call.
+# today_fmt = '%B %d, %Y'
+
+# The reST default role (used for this markup: `text`) to use
+# for all documents.
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for man page output ----------------------------------------------
+
+# Grouping the document tree for man pages.
+# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
+
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+# html_theme_path = ["."]
+# html_theme = '_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+# html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+# html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+# html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+# html_last_updated_fmt = '%b %d, %Y'
+git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
+           "-n1"]
+try:
+    html_last_updated_fmt = subprocess.Popen(
+        git_cmd, stdout=subprocess.PIPE).communicate()[0].decode()
+except Exception:
+    warnings.warn('Cannot get last updated time from git repository. '
+                  'Not setting "html_last_updated_fmt".')
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+# html_use_modindex = True
+
+# If false, no index is generated.
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+# html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+# html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'novadoc'
+
+
+# -- Options for LaTeX output -------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+# latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+# latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    ('index', 'CeilometerReleaseNotes.tex',
+     u'Ceilometer Release Notes Documentation',
+     u'Ceilometer Developers', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+# latex_use_parts = False
+
+
+# Additional stuff for the LaTeX preamble.
+# latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+# latex_appendices = []
+
+# If false, no module index is generated.
+# latex_use_modindex = True
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'ceilometerreleasenotes',
+     u'Ceilometer Release Notes Documentation', [u'Ceilometer Developers'], 1)
+]
+
+# If true, show URL addresses after external links.
+# man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    ('index', 'CeilometerReleaseNotes',
+     u'Ceilometer Release Notes Documentation',
+     u'Ceilometer Developers', 'CeilometerReleaseNotes',
+     'One line description of project.',
+     'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+# texinfo_appendices = []
+
+# If false, no module index is generated.
+# texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+# texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+# texinfo_no_detailmenu = False
diff --git a/api-ref/source/events.inc b/api-ref/source/events.inc
new file mode 100755
index 0000000000..0b0585bceb
--- /dev/null
+++ b/api-ref/source/events.inc
@@ -0,0 +1,93 @@
+.. -*- rst -*-
+
+======
+Events
+======
+
+Lists all events and shows details for an event.
+
+
+Show event details
+==================
+
+.. rest_method::  GET /v2/events/{message_id}
+
+Shows details for an event.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - message_id: message_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - traits: traits
+   - raw: raw
+   - generated: generated
+   - event_type: event_type
+   - message_id: message_id
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/event-show-response.json
+   :language: javascript
+
+
+
+
+List events
+===========
+
+.. rest_method::  GET /v2/events
+
+Lists all events.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - q: q
+   - limit: limit
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - traits: traits
+   - raw: raw
+   - generated: generated
+   - event_type: event_type
+   - message_id: message_id
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/events-list-response.json
+   :language: javascript
+
+
+
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
new file mode 100644
index 0000000000..18f7994f36
--- /dev/null
+++ b/api-ref/source/index.rst
@@ -0,0 +1,8 @@
+=========================
+ Ceilometer Release Notes
+=========================
+
+.. toctree::
+   :maxdepth: 1
+
+  
\ No newline at end of file
diff --git a/api-ref/source/meters.inc b/api-ref/source/meters.inc
new file mode 100755
index 0000000000..292fbaad23
--- /dev/null
+++ b/api-ref/source/meters.inc
@@ -0,0 +1,386 @@
+.. -*- rst -*-
+
+======
+Meters
+======
+
+Lists all meters, adds samples to meters, and lists samples for
+meters. For list operations, if you do not explicitly set the
+``limit`` query parameter, a default limit is applied. The default
+limit is the ``default_api_return_limit`` configuration option
+value.
+
+Also, computes and lists statistics for samples in a time range.
+You can use the ``aggregate`` query parameter in the ``statistics``
+URI to explicitly select the ``stddev``, ``cardinality``, or any
+other standard function. For example:
+
+::
+
+   GET /v2/meters/METER_NAME/statistics?aggregate.func=NAME
+   &
+   aggregate.param=VALUE
+
+The ``aggregate.param`` parameter value is optional for all
+functions except the ``cardinality`` function.
+
+The API silently ignores any duplicate aggregate function and
+parameter pairs.
+
+The API accepts and storage drivers support duplicate functions
+with different parameter values. In this example, the
+``cardinality`` function is accepted twice with two different
+parameter values:
+
+::
+
+   GET /v2/meters/METER_NAME/statistics?aggregate.func=cardinality
+   &
+   aggregate.param=resource_id
+           &
+   aggregate.func=cardinality
+   &
+   aggregate.param=project_id
+
+**Examples:**
+
+Use the ``stddev`` function to request the standard deviation of
+CPU utilization:
+
+::
+
+   GET /v2/meters/cpu_util/statistics?aggregate.func=stddev
+
+The response looks like this:
+
+.. code-block:: json
+
+   [
+       {
+           "aggregate": {
+               "stddev": 0.6858829
+           },
+           "duration_start": "2014-01-30T11:13:23",
+           "duration_end": "2014-01-31T16:07:13",
+           "duration": 104030,
+           "period": 0,
+           "period_start": "2014-01-30T11:13:23",
+           "period_end": "2014-01-31T16:07:13",
+           "groupby": null,
+           "unit": "%"
+       }
+   ]
+
+Use the ``cardinality`` function with the project ID to return the
+number of distinct tenants with images:
+
+::
+
+   GET /v2/meters/image/statistics?aggregate.func=cardinality
+   &
+   aggregate.param=project_id
+
+The following, more complex, example determines:
+
+- The number of distinct instances (``cardinality``)
+
+- The total number of instance samples (``count``) for a tenant in
+  15-minute intervals (``period`` and ``groupby`` options)
+
+::
+
+   GET /v2/meters/instance/statistics?aggregate.func=cardinality
+   &
+   aggregate.param=resource_id
+           &
+   aggregate.func=count
+   &
+   groupby=project_id
+   &
+   period=900
+
+The response looks like this:
+
+.. code-block:: json
+
+   [
+       {
+           "count": 19,
+           "aggregate": {
+               "count": 19,
+               "cardinality/resource_id": 3
+           },
+           "duration": 328.47803,
+           "duration_start": "2014-01-31T10:00:41.823919",
+           "duration_end": "2014-01-31T10:06:10.301948",
+           "period": 900,
+           "period_start": "2014-01-31T10:00:00",
+           "period_end": "2014-01-31T10:15:00",
+           "groupby": {
+               "project_id": "061a5c91811e4044b7dc86c6136c4f99"
+           },
+           "unit": "instance"
+       },
+       {
+           "count": 22,
+           "aggregate": {
+               "count": 22,
+               "cardinality/resource_id": 4
+           },
+           "duration": 808.00385,
+           "duration_start": "2014-01-31T10:15:15",
+           "duration_end": "2014-01-31T10:28:43.003840",
+           "period": 900,
+           "period_start": "2014-01-31T10:15:00",
+           "period_end": "2014-01-31T10:30:00",
+           "groupby": {
+               "project_id": "061a5c91811e4044b7dc86c6136c4f99"
+           },
+           "unit": "instance"
+       },
+       {
+           "count": 2,
+           "aggregate": {
+               "count": 2,
+               "cardinality/resource_id": 2
+           },
+           "duration": 0,
+           "duration_start": "2014-01-31T10:35:15",
+           "duration_end": "2014-01-31T10:35:15",
+           "period": 900,
+           "period_start": "2014-01-31T10:30:00",
+           "period_end": "2014-01-31T10:45:00",
+           "groupby": {
+               "project_id": "061a5c91811e4044b7dc86c6136c4f99"
+           },
+           "unit": "instance"
+       }
+   ]
+
+
+Show meter statistics
+=====================
+
+.. rest_method::  GET /v2/meters/{meter_name}/statistics
+
+Computes and lists statistics for samples in a time range.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - meter_name: meter_name
+   - q: q
+   - groupby: groupby
+   - period: period
+   - aggregate: aggregate
+   - limit: limit
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - count: count
+   - duration_start: duration_start
+   - min: min
+   - max: max
+   - duration_end: duration_end
+   - period: period
+   - sum: sum
+   - duration: duration
+   - period_end: period_end
+   - aggregate: aggregate
+   - period_start: period_start
+   - avg: avg
+   - groupby: groupby
+   - unit: unit
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/statistics-list-response.json
+   :language: javascript
+
+
+
+
+List meters
+===========
+
+.. rest_method::  GET /v2/meters
+
+Lists meters, based on the data recorded so far.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - q: q
+   - limit: limit
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - name: name
+   - resource_id: resource_id
+   - source: source
+   - meter_id: meter_id
+   - project_id: project_id
+   - type: type
+   - unit: unit
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/meters-list-response.json
+   :language: javascript
+
+
+
+
+List samples for meter
+======================
+
+.. rest_method::  GET /v2/meters/{meter_name}
+
+Lists samples for a meter, by meter name.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - meter_name: meter_name
+   - q: q
+   - limit: limit
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - resource_id: resource_id
+   - timestamp: timestamp
+   - meter: meter
+   - volume: volume
+   - source: source
+   - recorded_at: recorded_at
+   - project_id: project_id
+   - type: type
+   - id: id
+   - unit: unit
+   - metadata: metadata
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/samples-list-response.json
+   :language: javascript
+
+
+
+
+Add samples to meter
+====================
+
+.. rest_method::  POST /v2/meters/{meter_name}
+
+Adds samples to a meter, by meter name.
+
+If you attempt to add a sample that is not supported, this call
+returns the ``409`` response code.
+
+
+Normal response codes: 200
+Error response codes:409,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - resource_id: resource_id
+   - timestamp: timestamp
+   - meter: meter
+   - volume: volume
+   - source: source
+   - recorded_at: recorded_at
+   - project_id: project_id
+   - type: type
+   - id: id
+   - unit: unit
+   - metadata: metadata
+   - meter_name: meter_name
+   - direct: direct
+   - samples: samples
+
+Request Example
+---------------
+
+.. literalinclude:: ../samples/sample-create-request.json
+   :language: javascript
+
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - resource_id: resource_id
+   - timestamp: timestamp
+   - meter: meter
+   - volume: volume
+   - source: source
+   - recorded_at: recorded_at
+   - project_id: project_id
+   - type: type
+   - id: id
+   - unit: unit
+   - metadata: metadata
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/sample-show-response.json
+   :language: javascript
+
+
+
+
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
new file mode 100755
index 0000000000..10c6a67efb
--- /dev/null
+++ b/api-ref/source/parameters.yaml
@@ -0,0 +1,734 @@
+# variables in header
+{}
+
+# variables in path
+alarm_id_1:
+  description: |
+    The UUID of the alarm.
+  in: path
+  required: false
+  type: string
+message_id_1:
+  description: |
+    The UUID of the message.
+  in: path
+  required: false
+  type: string
+meter_name:
+  description: |
+    The name of the meter.
+  in: path
+  required: false
+  type: string
+resource_id_2:
+  description: |
+    The UUID of the resource.
+  in: path
+  required: false
+  type: string
+sample_id:
+  description: |
+    The UUID of the sample.
+  in: path
+  required: false
+  type: string
+
+# variables in query
+aggregate:
+  description: |
+    A list of selectable aggregation functions to apply.
+
+    For example:
+
+    ::
+
+       GET /v2/meters/METER_NAME/statistics?aggregate.func=cardinality
+       &
+       aggregate.param=resource_id
+       &
+       aggregate.func=cardinality
+       &
+       aggregate.param=project_id
+  in: query
+  required: false
+  type: object
+data:
+  description: |
+    An alarm within the request body.
+  in: query
+  required: false
+  type: string
+direct:
+  description: |
+    Indicates whether the samples are POST ed
+    directly to storage. Set ``?direct=True`` to POST the samples
+    directly to storage.
+  in: query
+  required: false
+  type: string
+groupby:
+  description: |
+    Fields for group by aggregation.
+  in: query
+  required: false
+  type: object
+limit:
+  description: |
+    Limits the maximum number of samples that the response returns.
+
+    For example:
+
+    ::
+
+       GET /v2/events?limit=1000
+  in: query
+  required: false
+  type: integer
+limit_1:
+  description: |
+    Requests a page size of items. Returns a number
+    of items up to a limit value. Use the ``limit`` parameter to make
+    an initial limited request and use the ID of the last-seen item
+    from the response as the ``marker`` parameter value in a
+    subsequent limited request.
+  in: query
+  required: false
+  type: integer
+meter_links:
+  description: |
+    Set ``?meter_links=1`` to return a self link and
+    related meter links.
+  in: query
+  required: false
+  type: integer
+period:
+  description: |
+    The period, in seconds, for which you want
+    statistics.
+  in: query
+  required: false
+  type: integer
+q:
+  description: |
+    Filters the response by one or more arguments.
+    For example: ``?q.field=Foo & q.value=my_text``.
+  in: query
+  required: false
+  type: array
+q_1:
+  description: |
+    Filters the response by one or more event arguments.
+
+    For example:
+
+    ::
+
+       GET /v2/events?q.field=Foo
+       &
+       q.value=my_text
+  in: query
+  required: false
+  type: array
+samples:
+  description: |
+    A list of samples.
+  in: query
+  required: false
+  type: array
+state_1:
+  description: |
+    The alarm state. A valid value is ``ok``,
+    ``alarm``, or ``insufficient data``.
+  in: query
+  required: true
+  type: string
+
+# variables in body
+alarm_actions:
+  description: |
+    The list of actions that the alarm performs.
+  in: body
+  required: true
+  type: array
+alarm_id:
+  description: |
+    The UUID of the alarm.
+  in: body
+  required: true
+  type: string
+alarm_storage:
+  description: |
+    Defines the capabilities for the storage that
+    stores persisting alarm definitions. A value of ``true`` indicates
+    that the capability is available.
+  in: body
+  required: true
+  type: object
+alarms:history:query:complex:
+  description: |
+    If ``true``, the complex query capability for
+    alarm history is available for the configured database back end.
+  in: body
+  required: true
+  type: boolean
+alarms:history:query:simple:
+  description: |
+    If ``true``, the simple query capability for
+    alarm history is available for the configured database back end.
+  in: body
+  required: true
+  type: boolean
+alarms:query:complex:
+  description: |
+    If ``true``, the complex query capability for
+    alarm definitions is available for the configured database back
+    end.
+  in: body
+  required: true
+  type: boolean
+alarms:query:simple:
+  description: |
+    If ``true``, the simple query capability for
+    alarm definitions is available for the configured database back
+    end.
+  in: body
+  required: true
+  type: boolean
+api:
+  description: |
+    A set of key and value pairs that contain the API
+    capabilities for the configured storage driver.
+  in: body
+  required: true
+  type: object
+avg:
+  description: |
+    The average of all volume values in the data.
+  in: body
+  required: true
+  type: number
+combination_rule:
+  description: |
+    The rules for the combination alarm type.
+  in: body
+  required: true
+  type: string
+count:
+  description: |
+    The number of samples seen.
+  in: body
+  required: true
+  type: integer
+description:
+  description: |
+    Describes the alarm.
+  in: body
+  required: true
+  type: string
+duration:
+  description: |
+    The number of seconds between the oldest and
+    newest date and time stamp.
+  in: body
+  required: true
+  type: number
+duration_end:
+  description: |
+    The date and time in UTC format of the query end
+    time.
+  in: body
+  required: true
+  type: string
+duration_start:
+  description: |
+    The date and time in UTC format of the query
+    start time.
+  in: body
+  required: true
+  type: string
+enabled:
+  description: |
+    If ``true``, evaluation and actioning is enabled
+    for the alarm.
+  in: body
+  required: true
+  type: boolean
+event_storage:
+  description: |
+    If ``true``, the capabilities for the storage
+    that stores persisting events is available.
+  in: body
+  required: true
+  type: object
+event_type:
+  description: |
+    The dotted string that represents the event.
+  in: body
+  required: true
+  type: string
+events:query:simple:
+  description: |
+    If ``true``, the simple query capability for
+    events is available for the configured database back end.
+  in: body
+  required: true
+  type: boolean
+generated:
+  description: |
+    The date and time when the event occurred.
+  in: body
+  required: true
+  type: string
+id:
+  description: |
+    The UUID of the sample.
+  in: body
+  required: true
+  type: string
+insufficient_data_actions:
+  description: |
+    The list of actions that the alarm performs when
+    the alarm state is ``insufficient_data``.
+  in: body
+  required: true
+  type: array
+links:
+  description: |
+    A list that contains a self link and associated
+    meter links.
+  in: body
+  required: true
+  type: array
+max:
+  description: |
+    The maximum volume seen in the data.
+  in: body
+  required: true
+  type: number
+message_id:
+  description: |
+    The UUID of the message.
+  in: body
+  required: true
+  type: string
+metadata:
+  description: |
+    An arbitrary set of one or more metadata key and
+    value pairs that are associated with the sample.
+  in: body
+  required: true
+  type: object
+metadata_1:
+  description: |
+    A set of one or more arbitrary metadata key and
+    value pairs that are associated with the resource.
+  in: body
+  required: true
+  type: object
+meter:
+  description: |
+    The meter name.
+  in: body
+  required: true
+  type: string
+meter_id:
+  description: |
+    The UUID of the meter.
+  in: body
+  required: true
+  type: string
+meters:query:complex:
+  description: |
+    If ``true``, the complex query capability for
+    meters is available for the configured database back end.
+  in: body
+  required: true
+  type: boolean
+meters:query:metadata:
+  description: |
+    If ``true``, the simple query capability for the
+    metadata of meters is available for the configured database back
+    end.
+  in: body
+  required: true
+  type: boolean
+meters:query:simple:
+  description: |
+    If ``true``, the simple query capability for
+    meters is available for the configured database back end.
+  in: body
+  required: true
+  type: boolean
+min:
+  description: |
+    The minimum volume seen in the data.
+  in: body
+  required: true
+  type: number
+name:
+  description: |
+    The name of the alarm.
+  in: body
+  required: true
+  type: string
+name_1:
+  description: |
+    The meter name.
+  in: body
+  required: true
+  type: string
+ok_actions:
+  description: |
+    The list of actions that the alarm performs when
+    the alarm state is ``ok``.
+  in: body
+  required: true
+  type: array
+period_end:
+  description: |
+    The period end date and time in UTC format.
+  in: body
+  required: true
+  type: string
+period_start:
+  description: |
+    The period start date and time in UTC format.
+  in: body
+  required: true
+  type: string
+project_id:
+  description: |
+    The UUID of the project or tenant that owns the
+    resource.
+  in: body
+  required: true
+  type: string
+project_id_1:
+  description: |
+    The UUID of the project.
+  in: body
+  required: true
+  type: string
+project_id_2:
+  description: |
+    The UUID of the owning project or tenant.
+  in: body
+  required: true
+  type: string
+raw:
+  description: |
+    A dictionary object that stores event messages
+    for future evaluation.
+  in: body
+  required: true
+  type: object
+recorded_at:
+  description: |
+    The date and time when the sample was recorded.
+  in: body
+  required: true
+  type: string
+repeat_actions:
+  description: |
+    If set to ``true``, the alarm notifications are
+    repeated. Otherwise, this value is ``false``.
+  in: body
+  required: true
+  type: boolean
+resource_id:
+  description: |
+    The UUID of the resource for which the
+    measurements are taken.
+  in: body
+  required: true
+  type: string
+resource_id_1:
+  description: |
+    The UUID of the resource.
+  in: body
+  required: true
+  type: string
+resources:query:complex:
+  description: |
+    If ``true``, the complex query capability for
+    resources is available for the configured database back end.
+  in: body
+  required: true
+  type: boolean
+resources:query:metadata:
+  description: |
+    If ``true``, the simple query capability for the
+    metadata of resources is available for the configured database
+    back end.
+  in: body
+  required: true
+  type: boolean
+resources:query:simple:
+  description: |
+    If ``true``, the simple query capability for
+    resources is available for the configured database back end.
+  in: body
+  required: true
+  type: boolean
+samples:query:complex:
+  description: |
+    If ``true``, the complex query capability for
+    samples is available for the configured database back end.
+  in: body
+  required: true
+  type: boolean
+samples:query:metadata:
+  description: |
+    If ``true``, the simple query capability for the
+    metadata of samples is available for the configured database back
+    end.
+  in: body
+  required: true
+  type: boolean
+samples:query:simple:
+  description: |
+    If ``true``, the simple query capability for
+    samples is available for the configured database back end.
+  in: body
+  required: true
+  type: boolean
+source:
+  description: |
+    The name of the source that identifies where the
+    sample comes from.
+  in: body
+  required: true
+  type: string
+source_1:
+  description: |
+    The name of the source from which the meter came.
+  in: body
+  required: true
+  type: string
+source_2:
+  description: |
+    The name of the source from which the resource
+    came.
+  in: body
+  required: true
+  type: string
+state:
+  description: |
+    The state of the alarm.
+  in: body
+  required: true
+  type: string
+state_timestamp:
+  description: |
+    The date and time of the alarm state.
+  in: body
+  required: true
+  type: string
+statistics:aggregation:selectable:avg:
+  description: |
+    If ``true``, the ``avg`` capability is available
+    for the configured database back end. Use the ``avg`` capability
+    to get average values for samples.
+  in: body
+  required: true
+  type: boolean
+statistics:aggregation:selectable:cardinality:
+  description: |
+    If ``true``, the ``cardinality`` capability is
+    available for the configured database back end. Use the
+    ``cardinality`` capability to get cardinality for samples.
+  in: body
+  required: true
+  type: boolean
+statistics:aggregation:selectable:count:
+  description: |
+    If ``true``, the ``count`` capability is
+    available for the configured database back end. Use the ``count``
+    capability to calculate the number of samples for a query.
+  in: body
+  required: true
+  type: boolean
+statistics:aggregation:selectable:max:
+  description: |
+    If ``true``, the ``max`` capability is available
+    for the configured database back end. . Use the ``max`` capability
+    to calculate the maximum value for a query.
+  in: body
+  required: true
+  type: boolean
+statistics:aggregation:selectable:min:
+  description: |
+    If ``true``, the ``min`` capability is available
+    for the configured database back end. Use the ``min`` capability
+    to calculate the minimum value for a query.
+  in: body
+  required: true
+  type: boolean
+statistics:aggregation:selectable:quartile:
+  description: |
+    If ``true``, the ``quartile`` capability is
+    available for the configured database back end. Use the
+    ``quartile`` capability to calculate the quartile of sample
+    volumes for a query.
+  in: body
+  required: true
+  type: boolean
+statistics:aggregation:selectable:stddev:
+  description: |
+    If ``true``, the ``stddev`` capability is
+    available for the configured database back end. Use the ``stddev``
+    capability to calculate the standard deviation of sample volumes
+    for a query.
+  in: body
+  required: true
+  type: boolean
+statistics:aggregation:selectable:sum:
+  description: |
+    If ``true``, the ``sum`` capability is available
+    for the configured database back end. Use the ``sum`` capability
+    to calculate the sum of sample volumes for a query.
+  in: body
+  required: true
+  type: boolean
+statistics:aggregation:standard:
+  description: |
+    If ``true``, the ``standard`` set of aggregation
+    capability is available for the configured database back end.
+  in: body
+  required: true
+  type: boolean
+statistics:groupby:
+  description: |
+    If ``true``, the ``groupby`` capability is
+    available for calculating statistics for the configured database
+    back end.
+  in: body
+  required: true
+  type: boolean
+statistics:query:complex:
+  description: |
+    If ``true``, the complex query capability for
+    statistics is available for the configured database back end.
+  in: body
+  required: true
+  type: boolean
+statistics:query:metadata:
+  description: |
+    If ``true``, the simple query capability for the
+    sample metadata that is used to calculate statistics is available
+    for the configured database back end.
+  in: body
+  required: true
+  type: boolean
+statistics:query:simple:
+  description: |
+    If ``true``, the simple query capability for
+    statistics is available for the configured database back end.
+  in: body
+  required: true
+  type: boolean
+storage:
+  description: |
+    If ``true``, the capabilities for the storage
+    that stores persisting samples is available.
+  in: body
+  required: true
+  type: object
+storage:production_ready:
+  description: |
+    If ``true``, the database back end is ready to
+    use in a production environment.
+  in: body
+  required: true
+  type: boolean
+sum:
+  description: |
+    The total of all of the volume values seen in the
+    data.
+  in: body
+  required: true
+  type: number
+threshold_rule:
+  description: |
+    The rules for the threshold alarm type.
+  in: body
+  required: true
+  type: string
+timestamp:
+  description: |
+    The date and time in UTC format when the
+    measurement was made.
+  in: body
+  required: true
+  type: string
+timestamp_1:
+  description: |
+    The date and time of the alarm.
+  in: body
+  required: true
+  type: string
+traits:
+  description: |
+    A list of objects. Each object contains key and
+    value pairs that describe the event.
+  in: body
+  required: true
+  type: array
+type:
+  description: |
+    The meter type.
+  in: body
+  required: true
+  type: string
+type_1:
+  description: |
+    The type of the alarm, which is either
+    ``threshold`` or ``combination``.
+  in: body
+  required: true
+  type: string
+type_2:
+  description: |
+    The meter type.  The type value is gauge, delta,
+    or cumulative.
+  in: body
+  required: true
+  type: string
+unit:
+  description: |
+    The unit of measure for the ``volume`` value.
+  in: body
+  required: true
+  type: string
+unit_1:
+  description: |
+    The unit of measure.
+  in: body
+  required: true
+  type: string
+unit_2:
+  description: |
+    The unit type of the data set.
+  in: body
+  required: true
+  type: string
+user_id:
+  description: |
+    The UUID of the user who either created or last
+    updated the resource.
+  in: body
+  required: true
+  type: string
+user_id_1:
+  description: |
+    The UUID of the user.
+  in: body
+  required: true
+  type: string
+volume:
+  description: |
+    The actual measured value.
+  in: body
+  required: true
+  type: number
+
diff --git a/api-ref/source/resources.inc b/api-ref/source/resources.inc
new file mode 100755
index 0000000000..6dc981ceb2
--- /dev/null
+++ b/api-ref/source/resources.inc
@@ -0,0 +1,95 @@
+.. -*- rst -*-
+
+=========
+Resources
+=========
+
+Lists all and gets information for resources.
+
+
+List resources
+==============
+
+.. rest_method::  GET /v2/resources
+
+Lists definitions for all resources.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - q: q
+   - meter_links: meter_links
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - links: links
+   - resource_id: resource_id
+   - source: source
+   - project_id: project_id
+   - metadata: metadata
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/resources-list-response.json
+   :language: javascript
+
+
+
+
+Show resource details
+=====================
+
+.. rest_method::  GET /v2/resources/{resource_id}
+
+Shows details for a resource, by resource ID.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - resource_id: resource_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - links: links
+   - resource_id: resource_id
+   - source: source
+   - project_id: project_id
+   - metadata: metadata
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/resource-show-response.json
+   :language: javascript
+
+
+
diff --git a/api-ref/source/samples.inc b/api-ref/source/samples.inc
new file mode 100755
index 0000000000..496224edc4
--- /dev/null
+++ b/api-ref/source/samples.inc
@@ -0,0 +1,111 @@
+.. -*- rst -*-
+
+=======
+Samples
+=======
+
+Lists all samples and gets information for a sample.
+
+For list operations, if you do not explicitly set the ``limit``
+query parameter, a default limit is applied. The default limit is
+the ``default_api_return_limit`` configuration option value.
+
+
+Show sample details
+===================
+
+.. rest_method::  GET /v2/samples/{sample_id}
+
+Shows details for a sample, by sample ID.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - sample_id: sample_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - resource_id: resource_id
+   - timestamp: timestamp
+   - meter: meter
+   - volume: volume
+   - source: source
+   - recorded_at: recorded_at
+   - project_id: project_id
+   - type: type
+   - id: id
+   - unit: unit
+   - metadata: metadata
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/sample-show-response.json
+   :language: javascript
+
+
+
+
+List samples
+============
+
+.. rest_method::  GET /v2/samples
+
+Lists all known samples, based on the data recorded so far.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - q: q
+   - limit: limit
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - resource_id: resource_id
+   - timestamp: timestamp
+   - meter: meter
+   - volume: volume
+   - source: source
+   - recorded_at: recorded_at
+   - project_id: project_id
+   - type: type
+   - id: id
+   - unit: unit
+   - metadata: metadata
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ../samples/samples-list-response.json
+   :language: javascript
+
+
+
diff --git a/api-ref/source/samples/alarm-show-response.json b/api-ref/source/samples/alarm-show-response.json
new file mode 100755
index 0000000000..802d472ecb
--- /dev/null
+++ b/api-ref/source/samples/alarm-show-response.json
@@ -0,0 +1,24 @@
+{
+    "alarm_actions": [
+        "http://site:8000/alarm"
+    ],
+    "alarm_id": null,
+    "combination_rule": null,
+    "description": "An alarm",
+    "enabled": true,
+    "insufficient_data_actions": [
+        "http://site:8000/nodata"
+    ],
+    "name": "SwiftObjectAlarm",
+    "ok_actions": [
+        "http://site:8000/ok"
+    ],
+    "project_id": "c96c887c216949acbdfbd8b494863567",
+    "repeat_actions": false,
+    "state": "ok",
+    "state_timestamp": "2013-11-21T12:33:08.486228",
+    "threshold_rule": null,
+    "timestamp": "2013-11-21T12:33:08.486221",
+    "type": "threshold",
+    "user_id": "c96c887c216949acbdfbd8b494863567"
+}
diff --git a/api-ref/source/samples/alarm-show-response.xml b/api-ref/source/samples/alarm-show-response.xml
new file mode 100755
index 0000000000..61ae48bba8
--- /dev/null
+++ b/api-ref/source/samples/alarm-show-response.xml
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<value>
+    <alarm_actions>
+        <item>http://site:8000/alarm</item>
+    </alarm_actions>
+    <alarm_id nil="true" />
+    <combination_rule nil="true" />
+    <description>An alarm</description>
+    <enabled>true</enabled>
+    <insufficient_data_actions>
+        <item>http://site:8000/nodata</item>
+    </insufficient_data_actions>
+    <name>SwiftObjectAlarm</name>
+    <ok_actions>
+        <item>http://site:8000/ok</item>
+    </ok_actions>
+    <project_id>c96c887c216949acbdfbd8b494863567</project_id>
+    <repeat_actions>false</repeat_actions>
+    <state>ok</state>
+    <state_timestamp>2013-11-21T12:33:08.486228</state_timestamp>
+    <threshold_rule nil="true" />
+    <timestamp>2013-11-21T12:33:08.486221</timestamp>
+    <type>threshold</type>
+    <user_id>c96c887c216949acbdfbd8b494863567</user_id>
+</value>
diff --git a/api-ref/source/samples/alarms-list-response.json b/api-ref/source/samples/alarms-list-response.json
new file mode 100755
index 0000000000..760b68b924
--- /dev/null
+++ b/api-ref/source/samples/alarms-list-response.json
@@ -0,0 +1,26 @@
+[
+    {
+        "alarm_actions": [
+            "http://site:8000/alarm"
+        ],
+        "alarm_id": null,
+        "combination_rule": null,
+        "description": "An alarm",
+        "enabled": true,
+        "insufficient_data_actions": [
+            "http://site:8000/nodata"
+        ],
+        "name": "SwiftObjectAlarm",
+        "ok_actions": [
+            "http://site:8000/ok"
+        ],
+        "project_id": "c96c887c216949acbdfbd8b494863567",
+        "repeat_actions": false,
+        "state": "ok",
+        "state_timestamp": "2013-11-21T12:33:08.486228",
+        "threshold_rule": null,
+        "timestamp": "2013-11-21T12:33:08.486221",
+        "type": "threshold",
+        "user_id": "c96c887c216949acbdfbd8b494863567"
+    }
+]
diff --git a/api-ref/source/samples/alarms-list-response.xml b/api-ref/source/samples/alarms-list-response.xml
new file mode 100755
index 0000000000..99ca555e98
--- /dev/null
+++ b/api-ref/source/samples/alarms-list-response.xml
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<values>
+    <value>
+        <alarm_actions>
+            <item>http://site:8000/alarm</item>
+        </alarm_actions>
+        <alarm_id nil="true" />
+        <combination_rule nil="true" />
+        <description>An alarm</description>
+        <enabled>true</enabled>
+        <insufficient_data_actions>
+            <item>http://site:8000/nodata</item>
+        </insufficient_data_actions>
+        <name>SwiftObjectAlarm</name>
+        <ok_actions>
+            <item>http://site:8000/ok</item>
+        </ok_actions>
+        <project_id>c96c887c216949acbdfbd8b494863567</project_id>
+        <repeat_actions>false</repeat_actions>
+        <state>ok</state>
+        <state_timestamp>2013-11-21T12:33:08.486228</state_timestamp>
+        <threshold_rule nil="true" />
+        <timestamp>2013-11-21T12:33:08.486221</timestamp>
+        <type>threshold</type>
+        <user_id>c96c887c216949acbdfbd8b494863567</user_id>
+    </value>
+</values>
diff --git a/api-ref/source/samples/capabilities-list-response.json b/api-ref/source/samples/capabilities-list-response.json
new file mode 100755
index 0000000000..8ec23e7995
--- /dev/null
+++ b/api-ref/source/samples/capabilities-list-response.json
@@ -0,0 +1,40 @@
+{
+    "alarm_storage": {
+        "storage:production_ready": true
+    },
+    "api": {
+        "alarms:history:query:complex": true,
+        "alarms:history:query:simple": true,
+        "alarms:query:complex": true,
+        "alarms:query:simple": true,
+        "events:query:simple": true,
+        "meters:query:complex": false,
+        "meters:query:metadata": true,
+        "meters:query:simple": true,
+        "resources:query:complex": false,
+        "resources:query:metadata": true,
+        "resources:query:simple": true,
+        "samples:query:complex": true,
+        "samples:query:metadata": true,
+        "samples:query:simple": true,
+        "statistics:aggregation:selectable:avg": true,
+        "statistics:aggregation:selectable:cardinality": true,
+        "statistics:aggregation:selectable:count": true,
+        "statistics:aggregation:selectable:max": true,
+        "statistics:aggregation:selectable:min": true,
+        "statistics:aggregation:selectable:quartile": false,
+        "statistics:aggregation:selectable:stddev": true,
+        "statistics:aggregation:selectable:sum": true,
+        "statistics:aggregation:standard": true,
+        "statistics:groupby": true,
+        "statistics:query:complex": false,
+        "statistics:query:metadata": true,
+        "statistics:query:simple": true
+    },
+    "event_storage": {
+        "storage:production_ready": true
+    },
+    "storage": {
+        "storage:production_ready": true
+    }
+}
diff --git a/api-ref/source/samples/capabilities-list-response.xml b/api-ref/source/samples/capabilities-list-response.xml
new file mode 100755
index 0000000000..d286c8cb25
--- /dev/null
+++ b/api-ref/source/samples/capabilities-list-response.xml
@@ -0,0 +1,131 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<value>
+   <api>
+      <item>
+         <key>statistics:query:complex</key>
+         <value>false</value>
+      </item>
+      <item>
+         <key>alarms:history:query:simple</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>meters:query:metadata</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>alarms:query:simple</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>resources:query:simple</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>statistics:aggregation:selectable:quartile</key>
+         <value>false</value>
+      </item>
+      <item>
+         <key>statistics:query:simple</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>statistics:aggregation:selectable:count</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>statistics:aggregation:selectable:min</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>statistics:aggregation:selectable:sum</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>alarms:query:complex</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>meters:query:complex</key>
+         <value>false</value>
+      </item>
+      <item>
+         <key>statistics:groupby</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>alarms:history:query:complex</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>meters:query:simple</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>samples:query:metadata</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>statistics:query:metadata</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>samples:query:simple</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>resources:query:metadata</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>statistics:aggregation:selectable:max</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>samples:query:complex</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>statistics:aggregation:standard</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>events:query:simple</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>statistics:aggregation:selectable:stddev</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>statistics:aggregation:selectable:avg</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>statistics:aggregation:selectable:cardinality</key>
+         <value>true</value>
+      </item>
+      <item>
+         <key>resources:query:complex</key>
+         <value>false</value>
+      </item>
+   </api>
+   <storage>
+      <item>
+         <key>storage:production_ready</key>
+         <value>true</value>
+      </item>
+   </storage>
+   <alarm_storage>
+      <item>
+         <key>storage:production_ready</key>
+         <value>true</value>
+      </item>
+   </alarm_storage>
+   <event_storage>
+      <item>
+         <key>storage:production_ready</key>
+         <value>true</value>
+      </item>
+   </event_storage>
+</value>
diff --git a/api-ref/source/samples/event-show-response.json b/api-ref/source/samples/event-show-response.json
new file mode 100755
index 0000000000..5c736a0742
--- /dev/null
+++ b/api-ref/source/samples/event-show-response.json
@@ -0,0 +1,18 @@
+{
+    "raw": {},
+    "traits": [
+        {
+            "type": "string",
+            "name": "action",
+            "value": "read"
+        },
+        {
+            "type": "string",
+            "name": "eventTime",
+            "value": "2015-10-28T20:26:58.545477+0000"
+        }
+    ],
+    "generated": "2015-10-28T20:26:58.546933",
+    "message_id": "bae43de6-e9fa-44ad-8c15-40a852584444",
+    "event_type": "http.request"
+}
diff --git a/api-ref/source/samples/events-list-response.json b/api-ref/source/samples/events-list-response.json
new file mode 100755
index 0000000000..4bd2dafd8c
--- /dev/null
+++ b/api-ref/source/samples/events-list-response.json
@@ -0,0 +1,20 @@
+[
+    {
+        "raw": {},
+        "traits": [
+            {
+                "type": "string",
+                "name": "action",
+                "value": "read"
+            },
+            {
+                "type": "string",
+                "name": "eventTime",
+                "value": "2015-10-28T20:26:58.545477+0000"
+            }
+        ],
+        "generated": "2015-10-28T20:26:58.546933",
+        "message_id": "bae43de6-e9fa-44ad-8c15-40a852584444",
+        "event_type": "http.request"
+    }
+]
diff --git a/api-ref/source/samples/meters-list-response.json b/api-ref/source/samples/meters-list-response.json
new file mode 100755
index 0000000000..f40c3c606e
--- /dev/null
+++ b/api-ref/source/samples/meters-list-response.json
@@ -0,0 +1,12 @@
+[
+    {
+        "meter_id": "YmQ5NDMxYzEtOGQ2OS00YWQzLTgwM2EtOGQ0YTZiODlmZDM2K2luc3RhbmNl",
+        "name": "instance",
+        "project_id": "35b17138-b364-4e6a-a131-8f3099c5be68",
+        "resource_id": "bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
+        "source": "openstack",
+        "type": "gauge",
+        "unit": "instance",
+        "user_id": "efd87807-12d2-4b38-9c70-5f5c2ac427ff"
+    }
+]
diff --git a/api-ref/source/samples/meters-list-response.xml b/api-ref/source/samples/meters-list-response.xml
new file mode 100755
index 0000000000..045f36683d
--- /dev/null
+++ b/api-ref/source/samples/meters-list-response.xml
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<values>
+   <value>
+      <name>instance</name>
+      <type>gauge</type>
+      <unit>instance</unit>
+      <resource_id>bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</resource_id>
+      <project_id>35b17138-b364-4e6a-a131-8f3099c5be68</project_id>
+      <user_id>efd87807-12d2-4b38-9c70-5f5c2ac427ff</user_id>
+      <source>openstack</source>
+      <meter_id>YmQ5NDMxYzEtOGQ2OS00YWQzLTgwM2EtOGQ0YTZiODlmZDM2K2luc3RhbmNl</meter_id>
+   </value>
+</values>
diff --git a/api-ref/source/samples/resource-show-response.json b/api-ref/source/samples/resource-show-response.json
new file mode 100755
index 0000000000..8679b5e78e
--- /dev/null
+++ b/api-ref/source/samples/resource-show-response.json
@@ -0,0 +1,20 @@
+{
+    "links": [
+        {
+            "href": "http://localhost:8777/v2/resources/bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
+            "rel": "self"
+        },
+        {
+            "href": "http://localhost:8777/v2/meters/volume?q.field=resource_id&q.value=bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
+            "rel": "volume"
+        }
+    ],
+    "metadata": {
+        "name1": "value1",
+        "name2": "value2"
+    },
+    "project_id": "35b17138-b364-4e6a-a131-8f3099c5be68",
+    "resource_id": "bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
+    "source": "openstack",
+    "user_id": "efd87807-12d2-4b38-9c70-5f5c2ac427ff"
+}
diff --git a/api-ref/source/samples/resource-show-response.xml b/api-ref/source/samples/resource-show-response.xml
new file mode 100755
index 0000000000..0516d54000
--- /dev/null
+++ b/api-ref/source/samples/resource-show-response.xml
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<value>
+   <resource_id>bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</resource_id>
+   <project_id>35b17138-b364-4e6a-a131-8f3099c5be68</project_id>
+   <user_id>efd87807-12d2-4b38-9c70-5f5c2ac427ff</user_id>
+   <metadata>
+      <item>
+         <key>name2</key>
+         <value>value2</value>
+      </item>
+      <item>
+         <key>name1</key>
+         <value>value1</value>
+      </item>
+   </metadata>
+   <links>
+      <item>
+         <href>http://localhost:8777/v2/resources/bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</href>
+         <rel>self</rel>
+      </item>
+      <item>
+         <href>http://localhost:8777/v2/meters/volume?q.field=resource_id&amp;q.value=bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</href>
+         <rel>volume</rel>
+      </item>
+   </links>
+   <source>openstack</source>
+</value>
diff --git a/api-ref/source/samples/resources-list-response.json b/api-ref/source/samples/resources-list-response.json
new file mode 100755
index 0000000000..3655077ee9
--- /dev/null
+++ b/api-ref/source/samples/resources-list-response.json
@@ -0,0 +1,22 @@
+[
+    {
+        "links": [
+            {
+                "href": "http://localhost:8777/v2/resources/bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
+                "rel": "self"
+            },
+            {
+                "href": "http://localhost:8777/v2/meters/volume?q.field=resource_id&q.value=bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
+                "rel": "volume"
+            }
+        ],
+        "metadata": {
+            "name1": "value1",
+            "name2": "value2"
+        },
+        "project_id": "35b17138-b364-4e6a-a131-8f3099c5be68",
+        "resource_id": "bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
+        "source": "openstack",
+        "user_id": "efd87807-12d2-4b38-9c70-5f5c2ac427ff"
+    }
+]
diff --git a/api-ref/source/samples/resources-list-response.xml b/api-ref/source/samples/resources-list-response.xml
new file mode 100755
index 0000000000..9041d6e7af
--- /dev/null
+++ b/api-ref/source/samples/resources-list-response.xml
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<values>
+   <value>
+      <resource_id>bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</resource_id>
+      <project_id>35b17138-b364-4e6a-a131-8f3099c5be68</project_id>
+      <user_id>efd87807-12d2-4b38-9c70-5f5c2ac427ff</user_id>
+      <metadata>
+         <item>
+            <key>name2</key>
+            <value>value2</value>
+         </item>
+         <item>
+            <key>name1</key>
+            <value>value1</value>
+         </item>
+      </metadata>
+      <links>
+         <item>
+            <href>http://localhost:8777/v2/resources/bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</href>
+            <rel>self</rel>
+         </item>
+         <item>
+            <href>http://localhost:8777/v2/meters/volume?q.field=resource_id&amp;q.value=bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</href>
+            <rel>volume</rel>
+         </item>
+      </links>
+      <source>openstack</source>
+   </value>
+</values>
diff --git a/api-ref/source/samples/sample-create-request.json b/api-ref/source/samples/sample-create-request.json
new file mode 100755
index 0000000000..38a94eedd2
--- /dev/null
+++ b/api-ref/source/samples/sample-create-request.json
@@ -0,0 +1,17 @@
+{
+    "id": "8db08c68-bc70-11e4-a8c4-fa163e1d1a9b",
+    "metadata": {
+        "name1": "value1",
+        "name2": "value2"
+    },
+    "meter": "instance",
+    "project_id": "35b17138-b364-4e6a-a131-8f3099c5be68",
+    "recorded_at": "2015-02-24T22:00:32.747930",
+    "resource_id": "bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
+    "source": "openstack",
+    "timestamp": "2015-02-24T22:00:32.747930",
+    "type": "gauge",
+    "unit": "instance",
+    "user_id": "efd87807-12d2-4b38-9c70-5f5c2ac427ff",
+    "volume": 1.0
+}
diff --git a/api-ref/source/samples/sample-create-request.xml b/api-ref/source/samples/sample-create-request.xml
new file mode 100755
index 0000000000..21af1af55c
--- /dev/null
+++ b/api-ref/source/samples/sample-create-request.xml
@@ -0,0 +1,23 @@
+<value>
+  <id>8db08c68-bc70-11e4-a8c4-fa163e1d1a9b</id>
+  <meter>instance</meter>
+  <type>gauge</type>
+  <unit>instance</unit>
+  <volume>1.0</volume>
+  <user_id>efd87807-12d2-4b38-9c70-5f5c2ac427ff</user_id>
+  <project_id>35b17138-b364-4e6a-a131-8f3099c5be68</project_id>
+  <resource_id>bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</resource_id>
+  <source>openstack</source>
+  <timestamp>2015-02-24T22:00:32.747930</timestamp>
+  <recorded_at>2015-02-24T22:00:32.747930</recorded_at>
+  <metadata>
+    <item>
+      <key>name2</key>
+      <value>value2</value>
+    </item>
+    <item>
+      <key>name1</key>
+      <value>value1</value>
+    </item>
+  </metadata>
+</value>
diff --git a/api-ref/source/samples/sample-show-response.json b/api-ref/source/samples/sample-show-response.json
new file mode 100755
index 0000000000..9b3df91b28
--- /dev/null
+++ b/api-ref/source/samples/sample-show-response.json
@@ -0,0 +1,17 @@
+{
+    "id": "9b23b398-6139-11e5-97e9-bc764e045bf6",
+    "metadata": {
+        "name1": "value1",
+        "name2": "value2"
+    },
+    "meter": "instance",
+    "project_id": "35b17138-b364-4e6a-a131-8f3099c5be68",
+    "recorded_at": "2015-09-22T14:52:54.850725",
+    "resource_id": "bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
+    "source": "openstack",
+    "timestamp": "2015-09-22T14:52:54.850718",
+    "type": "gauge",
+    "unit": "instance",
+    "user_id": "efd87807-12d2-4b38-9c70-5f5c2ac427ff",
+    "volume": 1
+}
diff --git a/api-ref/source/samples/sample-show-response.xml b/api-ref/source/samples/sample-show-response.xml
new file mode 100755
index 0000000000..a11b74fb42
--- /dev/null
+++ b/api-ref/source/samples/sample-show-response.xml
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<value>
+   <id>9b23b398-6139-11e5-97e9-bc764e045bf6</id>
+   <meter>instance</meter>
+   <type>gauge</type>
+   <unit>instance</unit>
+   <volume>1.0</volume>
+   <user_id>efd87807-12d2-4b38-9c70-5f5c2ac427ff</user_id>
+   <project_id>35b17138-b364-4e6a-a131-8f3099c5be68</project_id>
+   <resource_id>bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</resource_id>
+   <source>openstack</source>
+   <timestamp>2015-09-22T14:52:54.850718</timestamp>
+   <recorded_at>2015-09-22T14:52:54.850725</recorded_at>
+   <metadata>
+      <item>
+         <key>name2</key>
+         <value>value2</value>
+      </item>
+      <item>
+         <key>name1</key>
+         <value>value1</value>
+      </item>
+   </metadata>
+</value>
diff --git a/api-ref/source/samples/samples-list-response.json b/api-ref/source/samples/samples-list-response.json
new file mode 100755
index 0000000000..7d8e5bc7ef
--- /dev/null
+++ b/api-ref/source/samples/samples-list-response.json
@@ -0,0 +1,19 @@
+[
+    {
+        "id": "9b23b398-6139-11e5-97e9-bc764e045bf6",
+        "metadata": {
+            "name1": "value1",
+            "name2": "value2"
+        },
+        "meter": "instance",
+        "project_id": "35b17138-b364-4e6a-a131-8f3099c5be68",
+        "recorded_at": "2015-09-22T14:52:54.850725",
+        "resource_id": "bd9431c1-8d69-4ad3-803a-8d4a6b89fd36",
+        "source": "openstack",
+        "timestamp": "2015-09-22T14:52:54.850718",
+        "type": "gauge",
+        "unit": "instance",
+        "user_id": "efd87807-12d2-4b38-9c70-5f5c2ac427ff",
+        "volume": 1
+    }
+]
diff --git a/api-ref/source/samples/samples-list-response.xml b/api-ref/source/samples/samples-list-response.xml
new file mode 100755
index 0000000000..04f441752d
--- /dev/null
+++ b/api-ref/source/samples/samples-list-response.xml
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<values>
+   <value>
+      <id>9b23b398-6139-11e5-97e9-bc764e045bf6</id>
+      <meter>instance</meter>
+      <type>gauge</type>
+      <unit>instance</unit>
+      <volume>1.0</volume>
+      <user_id>efd87807-12d2-4b38-9c70-5f5c2ac427ff</user_id>
+      <project_id>35b17138-b364-4e6a-a131-8f3099c5be68</project_id>
+      <resource_id>bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</resource_id>
+      <source>openstack</source>
+      <timestamp>2015-09-22T14:52:54.850718</timestamp>
+      <recorded_at>2015-09-22T14:52:54.850725</recorded_at>
+      <metadata>
+         <item>
+            <key>name2</key>
+            <value>value2</value>
+         </item>
+         <item>
+            <key>name1</key>
+            <value>value1</value>
+         </item>
+      </metadata>
+   </value>
+</values>
diff --git a/api-ref/source/samples/statistics-list-response.json b/api-ref/source/samples/statistics-list-response.json
new file mode 100755
index 0000000000..1d8e1bc8f7
--- /dev/null
+++ b/api-ref/source/samples/statistics-list-response.json
@@ -0,0 +1,16 @@
+[
+    {
+        "avg": 4.5,
+        "count": 10,
+        "duration": 300,
+        "duration_end": "2013-01-04T16:47:00",
+        "duration_start": "2013-01-04T16:42:00",
+        "max": 9,
+        "min": 1,
+        "period": 7200,
+        "period_end": "2013-01-04T18:00:00",
+        "period_start": "2013-01-04T16:00:00",
+        "sum": 45,
+        "unit": "GiB"
+    }
+]
diff --git a/api-ref/source/samples/statistics-list-response.xml b/api-ref/source/samples/statistics-list-response.xml
new file mode 100755
index 0000000000..503e068de6
--- /dev/null
+++ b/api-ref/source/samples/statistics-list-response.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<values>
+  <value>
+    <avg>4.5</avg>
+    <count>10</count>
+    <duration>300.0</duration>
+    <duration_end>2013-01-04T16:47:00</duration_end>
+    <duration_start>2013-01-04T16:42:00</duration_start>
+    <max>9.0</max>
+    <min>1.0</min>
+    <period>7200</period>
+    <period_end>2013-01-04T18:00:00</period_end>
+    <period_start>2013-01-04T16:00:00</period_start>
+    <sum>45.0</sum>
+    <unit>GiB</unit>
+  </value>
+</values>
diff --git a/test-requirements.txt b/test-requirements.txt
index f2f174b12b..f7a2d19f5f 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -33,3 +33,4 @@ os-testr>=0.4.1 # Apache-2.0
 tempest>=11.0.0  # Apache-2.0
 WebTest>=2.0 # MIT
 pifpaf>=0.0.11
+os-api-ref>=0.1.0 # Apache-2.0s
diff --git a/tox.ini b/tox.ini
index 2b3f8c0318..fd328a282d 100644
--- a/tox.ini
+++ b/tox.ini
@@ -138,3 +138,9 @@ show-source = True
 import_exceptions =
     ceilometer.i18n
 local-check-factory = ceilometer.hacking.checks.factory
+
+[testenv:api-ref]
+commands =
+  rm -rf api-ref/build
+  sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
+