diff --git a/api-ref/source/v1/deployments.inc b/api-ref/source/v1/deployments.inc
index 1408b65c..78e61df5 100644
--- a/api-ref/source/v1/deployments.inc
+++ b/api-ref/source/v1/deployments.inc
@@ -29,18 +29,19 @@ Response Codes
 
 .. rest_status_code:: success status.yaml
 
-   - 200
+    - 200
 
 .. rest_status_code:: error status.yaml
 
-   - 401
+    - 401
 
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - deployments: deployments
+    - X-Openstack-Request-Id: request_id
+    - deployments: deployments
 
 Response Example
 ----------------
diff --git a/api-ref/source/v1/environments.inc b/api-ref/source/v1/environments.inc
index 079f71bb..657ab1bf 100644
--- a/api-ref/source/v1/environments.inc
+++ b/api-ref/source/v1/environments.inc
@@ -4,6 +4,16 @@
 Environments
 ============
 
+An environment is a set of logically connected applications that are grouped
+together for easy management. By default, each environment has a single
+network for all its applications, and the deployment of the environment is
+defined in a single heat stack. Applications in different environments are
+always independent from one another.
+
+An environment is a single unit of deployment. This means that you can not only
+deploy an environment that contains a single application but an environment
+that contains multiple applications.
+
 List environments
 =================
 
@@ -20,9 +30,8 @@ Response Codes
 
 .. rest_status_code:: error status.yaml
 
-   - 400
    - 401
-   - 500
+   - 403
 
 Request Parameters
 ------------------
@@ -39,10 +48,10 @@ Response Parameters
    - X-Openstack-Request-Id: request_id
    - environments: environments
    - status: env_status
-   - updated: updated
-   - networking: networking
-   - name: env_name
    - created: created
+   - updated: updated
+   - name: env_name
+   - description_text: env_description
    - tenant_id: tenant_id
    - version: env_version
    - id: env_id
@@ -71,6 +80,7 @@ Response Codes
 
    - 400
    - 401
+   - 403
    - 409
 
 Request Parameters
@@ -94,10 +104,13 @@ Response Parameters
    - X-Openstack-Request-Id: request_id
    - id: env_id
    - name: env_name
+   - description_text: env_description
    - created: created
    - updated: updated
    - tenant_id: tenant_id
    - version: env_version
+   - services: services
+   - acquired_by: acquired_by
 
 Response Example
 ----------------
@@ -105,33 +118,34 @@ Response Example
 .. literalinclude:: samples/environment-create-response.json
    :language: javascript
 
-Update environment
+Rename environment
 ==================
 
-.. rest_method::  PUT /environments/<env_id>
+.. rest_method::  PUT /environments/{env_id}
 
-Updates an environment.
+Renames an environment.
 
 Response Codes
 --------------
 
 .. rest_status_code:: success status.yaml
 
-   - 202
+   - 200
 
 .. rest_status_code:: error status.yaml
 
    - 400
+   - 401
    - 403
    - 404
    - 409
-   - 500
 
 Request Parameters
 ------------------
 
 .. rest_parameters:: parameters.yaml
 
+   - env_id: env_id_url
    - name: env_name_update
 
 Request Example
@@ -148,10 +162,13 @@ Response Parameters
    - X-Openstack-Request-Id: request_id
    - id: env_id
    - name: env_name
+   - description_text: env_description
    - created: created
    - updated: updated
    - tenant_id: tenant_id
    - version: env_version
+   - services: services
+   - acquired_by: acquired_by
 
 Response Example
 ----------------
@@ -162,7 +179,7 @@ Response Example
 Show environment details
 ========================
 
-.. rest_method::  GET /environments/{id}
+.. rest_method::  GET /environments/{env_id}
 
 Shows details for a environment.
 
@@ -175,17 +192,16 @@ Response Codes
 
 .. rest_status_code:: error status.yaml
 
-   - 400
    - 401
+   - 403
    - 404
-   - 500
 
 Request Parameters
 ------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - id: env_id_url
+   - env_id: env_id_url
 
 Response Parameters
 -------------------
@@ -193,15 +209,15 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - X-Openstack-Request-Id: request_id
-   - status: env_status
-   - updated: updated
-   - networking: networking
+   - id: env_id
    - name: env_name
+   - description_text: env_description
    - created: created
+   - updated: updated
    - tenant_id: tenant_id
    - version: env_version
    - services: services
-   - id: env_id
+   - acquired_by: acquired_by
 
 Response Example
 ----------------
@@ -212,7 +228,7 @@ Response Example
 Delete environment
 ==================
 
-.. rest_method::  DELETE /environments/{id}
+.. rest_method::  DELETE /environments/{env_id}
 
 Remove specified Environment.
 
@@ -225,16 +241,16 @@ Response Codes
 
 .. rest_status_code:: error status.yaml
 
+   - 401
    - 403
    - 404
-   - 500
 
 Request Parameters
 ------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - id: env_id_url
+   - env_id: env_id_url
    - abandon: abandon
 
 Response Parameters
@@ -258,9 +274,9 @@ Response Codes
 
 .. rest_status_code:: error status.yaml
 
-   - 400
    - 401
-   - 500
+   - 403
+   - 404
 
 Request Parameters
 ------------------
@@ -278,8 +294,8 @@ Response Parameters
    - X-Openstack-Request-Id: request_id
    - defaultNetworks: env_default_networks
    - region: env_region
-   - name: env_name
    - regions: regions
+   - name: env_name
    - services: services
    - ?: env_model
 
@@ -292,9 +308,9 @@ Response Example
 Update environment model
 ========================
 
-.. rest_method::  PATCH /environments/<env_id>/model/
+.. rest_method::  PATCH /environments/{env_id}/model/
 
-Update an Environment model.
+Update an environment model.
 
 Response Codes
 --------------
@@ -306,17 +322,17 @@ Response Codes
 .. rest_status_code:: error status.yaml
 
    - 400
+   - 401
    - 403
    - 404
    - 409
-   - 500
 
 Request Parameters
 ------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - name: env_name_update
+   - env_id: env_id_url
 
 Request Example
 ---------------
@@ -332,8 +348,8 @@ Response Parameters
    - X-Openstack-Request-Id: request_id
    - defaultNetworks: env_default_networks
    - region: env_region
-   - name: env_name
    - regions: regions
+   - name: env_name
    - services: services
    - ?: env_model
 
@@ -346,9 +362,9 @@ Response Example
 Get environment last status
 ===========================
 
-.. rest_method::  GET /environments/{id}/lastStatus
+.. rest_method::  GET /environments/{env_id}/lastStatus
 
-Get last status for a environment.
+Get the last status for the environment for each service in the environment.
 
 Response Codes
 --------------
@@ -361,15 +377,15 @@ Response Codes
 
    - 400
    - 401
+   - 403
    - 404
-   - 500
 
 Request Parameters
 ------------------
 
 .. rest_parameters:: parameters.yaml
 
-   - id: env_id_url
+   - env_id: env_id_url
 
 Response Parameters
 -------------------
@@ -377,7 +393,7 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - X-Openstack-Request-Id: request_id
-   - uuid: last_status_uuid
+   - lastStatuses: env_last_status
 
 Response Example
 ----------------
diff --git a/api-ref/source/v1/parameters.yaml b/api-ref/source/v1/parameters.yaml
index 94340dcd..d50bebd3 100644
--- a/api-ref/source/v1/parameters.yaml
+++ b/api-ref/source/v1/parameters.yaml
@@ -79,6 +79,7 @@ template_is_public_url:
       are listed
   in: path
   required: false
+  default: false
   type: boolean
 
 # variables in query
@@ -184,6 +185,13 @@ search:
   type: string
 
 # variables in body
+acquired_by:
+  description: |
+    The session that is currently `deploying` the environment. Returns the
+    `first` session id that is in ``DEPLOYING`` state for the environment.
+  in: body
+  required: true
+  type: string
 all_categories:
   description: |
     All categories available in the application catalog.
@@ -265,26 +273,57 @@ enabled:
   type: boolean
 env_default_networks:
   description: |
-    The default networks of the environment.
+    The default networking information of the environment. The information
+    includes the ``name`` of the network, along with the ``type`` and ``id``
+    of the network, contained in the ``?`` property.
+
+    An example ``defaultNetworks`` object looks like::
+
+        "defaultNetworks": {
+            "environment": {
+                "internalNetworkName": "net_two",
+                "?": {
+                    "type": "io.murano.resources.ExistingNeutronNetwork",
+                    "id": "594e94fcfe4c48ef8f9b55edb3b9f177"
+                }
+            },
+            "flat": null
+        }
   in: body
   required: true
-  type: array
+  type: object
+env_description:
+  description: |
+    The description of the environment.
+  in: body
+  required: true
+  type: string
 env_id:
   description: |
     The UUID of the environment.
   in: body
   required: true
   type: string
-env_model:
+env_last_status:
   description: |
-    The ``?`` sections of the environment.
+    Shows the most recent status of the environment for each service in the
+    environment. The response object includes detailed information
+    by ``service_id``.
   in: body
   required: true
-  type: array
+  type: object
+env_model:
+  description: |
+    The ``?`` section of the environment, containing information about the
+    environment model, including its ``type``, ``id`` and associated
+    ``metadata``.
+  in: body
+  required: true
+  type: object
 env_name:
   description: |
-    A name for the environment. Name must be at least
-    one non-white space symbol.
+    A name for the environment. Name must be at least one non-white space
+    symbol and less than 256 characters long.
   in: body
   required: true
   type: string
@@ -341,12 +380,6 @@ is_public:
   in: body
   required: true
   type: boolean
-last_status_uuid:
-  description: |
-    A list of environment last status object.
-  in: body
-  required: true
-  type: array
 networking:
   description: |
     Current network of the environment.
@@ -409,10 +442,10 @@ pkg_type:
   type: string
 regions:
   description: |
-    The regions detail of the cloud.
+    Detailed region information for the cloud environment.
   in: body
   required: true
-  type: array
+  type: object
 services:
   description: |
     A list of ``service`` objects.
diff --git a/api-ref/source/v1/samples/environment-create-response.json b/api-ref/source/v1/samples/environment-create-response.json
index 6d67d370..1b5ba062 100644
--- a/api-ref/source/v1/samples/environment-create-response.json
+++ b/api-ref/source/v1/samples/environment-create-response.json
@@ -1,8 +1,12 @@
 {
-    "id": "ce373a477f211e187a55404a662f968",
-    "name": "env_name",
-    "created": "2013-11-30T03:23:42Z",
-    "updated": "2013-11-30T03:23:44Z",
-    "tenant_id": "0849006f7ce94961b3aab4e46d6f229a",
-    "version": 0
-}
+  "status": "ready",
+  "updated": "2017-04-27T15:36:02",
+  "created": "2017-04-27T15:36:02",
+  "tenant_id": "cca37eef752244d99945a4123f30ff79",
+  "acquired_by": null,
+  "services": [],
+  "version": 0,
+  "description_text": "",
+  "id": "a2977db57398401aba5804ef2211a2a3",
+  "name": "env_name"
+}
\ No newline at end of file
diff --git a/api-ref/source/v1/samples/environment-show-response.json b/api-ref/source/v1/samples/environment-show-response.json
index a3f7272a..c6d04c17 100644
--- a/api-ref/source/v1/samples/environment-show-response.json
+++ b/api-ref/source/v1/samples/environment-show-response.json
@@ -1,35 +1,36 @@
 {
-    "status": "ready",
-    "updated": "2014-05-14T13:12:26",
-    "networking": {},
-    "name": "quick-env-2",
-    "created": "2014-05-14T13:09:55",
-    "tenant_id": "726ed856965f43cc8e565bc991fa76c3",
-    "version": 1,
-    "services": [
-        {
-            "instance": {
-                "flavor": "m1.medium",
-                "image": "cloud-fedora-v3",
-                "name": "exgchhv6nbika2",
-                "ipAddresses": [
-                    "10.0.0.200"
-                ],
-                "?": {
-                    "type": "io.murano.resources.Instance",
-                    "id": "14cce9d9-aaa1-4f09-84a9-c4bb859edaff"
-                }
-            },
-            "name": "rewt4w56",
+  "status": "ready",
+  "updated": "2017-04-27T15:36:02",
+  "created": "2017-04-27T15:36:02",
+  "tenant_id": "cca37eef752244d99945a4123f30ff79",
+  "acquired_by": null,
+  "services": [
+    {
+        "instance": {
+            "flavor": "m1.medium",
+            "image": "cloud-fedora-v3",
+            "name": "exgchhv6nbika2",
+            "ipAddresses": [
+                "10.0.0.200"
+            ],
             "?": {
-                "status": "ready",
-                "_26411a1861294160833743e45d0eaad9": {
-                    "name": "Telnet"
-                },
-                "type": "io.murano.apps.linux.Telnet",
-                "id": "446373ef-03b5-4925-b095-6c56568fa518"
+                "type": "io.murano.resources.Instance",
+                "id": "14cce9d9-aaa1-4f09-84a9-c4bb859edaff"
             }
+        },
+        "name": "rewt4w56",
+        "?": {
+            "status": "ready",
+            "_26411a1861294160833743e45d0eaad9": {
+                "name": "Telnet"
+            },
+            "type": "io.murano.apps.linux.Telnet",
+            "id": "446373ef-03b5-4925-b095-6c56568fa518"
         }
-    ],
-    "id": "20d4a012628e4073b48490a336a8acbf"
-}
+    }
+  ],
+  "version": 0,
+  "description_text": "",
+  "id": "a2977db57398401aba5804ef2211a2a3",
+  "name": "env_name"
+}
\ No newline at end of file
diff --git a/api-ref/source/v1/samples/environment-update-response.json b/api-ref/source/v1/samples/environment-update-response.json
index 9f7f42a4..a88132ac 100644
--- a/api-ref/source/v1/samples/environment-update-response.json
+++ b/api-ref/source/v1/samples/environment-update-response.json
@@ -1,8 +1,12 @@
 {
-    "id": "ce373a477f211e187a55404a662f968",
-    "name": "env_name_changed",
-    "created": "2013-11-30T03:23:42Z",
-    "updated": "2013-11-30T03:45:54Z",
-    "tenant_id": "0849006f7ce94961b3aab4e46d6f229a",
-    "version": 0
-}
+  "status": "ready",
+  "updated": "2017-04-27T16:01:29",
+  "created": "2017-04-27T15:33:55",
+  "tenant_id": "cca37eef752244d99945a4123f30ff79",
+  "acquired_by": null,
+  "services": [],
+  "version": 0,
+  "description_text": "",
+  "id": "f199275420ff4e938e0307b0cf68374d",
+  "name": "env_name_changed"
+}
\ No newline at end of file
diff --git a/api-ref/source/v1/sessions.inc b/api-ref/source/v1/sessions.inc
index 0077b3d1..33b1ab0a 100644
--- a/api-ref/source/v1/sessions.inc
+++ b/api-ref/source/v1/sessions.inc
@@ -49,6 +49,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - created: created
    - updated: updated
    - environment_id: env_id
@@ -121,6 +122,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - id: session_id
    - environment_id: env_id
    - created: created
diff --git a/api-ref/source/v1/templates.inc b/api-ref/source/v1/templates.inc
index 432b9fb9..39e983b0 100644
--- a/api-ref/source/v1/templates.inc
+++ b/api-ref/source/v1/templates.inc
@@ -83,6 +83,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - templates: templates
    - created: created
    - updated: updated
@@ -137,6 +138,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - created: created
    - updated: updated
    - name: template_name
@@ -183,6 +185,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - created: created
    - updated: updated
    - name: template_name
@@ -263,6 +266,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - updated: updated
    - created: created
    - tenant_id: tenant_id
@@ -336,15 +340,16 @@ Request Parameters
 Response Parameters
 -------------------
 
-    - updated: updated
-    - created: created
-    - tenant_id: tenant_id
-    - services: template_services
-    - version: template_version
-    - description_text: template_description
-    - is_public: template_is_public
-    - id: template_id
-    - name: template_name
+   - X-Openstack-Request-Id: request_id
+   - updated: updated
+   - created: created
+   - tenant_id: tenant_id
+   - services: template_services
+   - version: template_version
+   - description_text: template_description
+   - is_public: template_is_public
+   - id: template_id
+   - name: template_name
 
 Response Example
 ----------------
@@ -391,6 +396,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - service: template_service
 
 Response Example
@@ -438,6 +444,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - environment_id: env_id
    - name: env_name
    - created: created
@@ -495,6 +502,7 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
+   - X-Openstack-Request-Id: request_id
    - environment_id: env_id
    - name: env_name
    - created: created