diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index dd40dd5fcb7a..711dc0d32573 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -56,10 +56,10 @@
 .. include:: os-security-groups.inc
 .. include:: os-security-group-default-rules.inc
 .. include:: os-security-group-rules.inc
-.. include:: os-server-external-events.inc
 .. include:: os-server-groups.inc
 .. include:: os-services.inc
 .. include:: os-simple-tenant-usage.inc
 .. include:: os-tenant-network.inc
 .. include:: os-volumes.inc
+.. include:: os-server-external-events.inc
 .. include:: extensions.inc
diff --git a/api-ref/source/os-server-external-events.inc b/api-ref/source/os-server-external-events.inc
index 990e1158e7fa..c652f3299bc6 100644
--- a/api-ref/source/os-server-external-events.inc
+++ b/api-ref/source/os-server-external-events.inc
@@ -1,12 +1,19 @@
 .. -*- rst -*-
-.. needs:parameter_verification
-.. needs:example_verification
-.. needs:body_verification
 
 ====================================================
  Create external events (os-server-external-events)
 ====================================================
 
+.. warning::
+   This is an ``admin`` level service API only designed to be used by
+   other OpenStack services. The point of this API is to coordinate
+   between Nova and Neutron (and potentially future services) on
+   activities they both need to be involved in, such as network
+   hotplugging.
+
+   Unless you are writing Neutron code you **should not** be using
+   this API.
+
 Creates one or more external events. The API dispatches each event to a
 server instance.
 
@@ -15,14 +22,22 @@ Run Events
 
 .. rest_method:: POST /v2.1/{tenant_id}/os-server-external-events
 
-Creates one or more external events, which the API dispatches to the instance.
+Creates one or more external events, which the API dispatches to the
+host a server is assigned to. If the server is not currently assigned
+to a host the event will not be delivered.
 
-You must assign this instance to a host. Otherwise, this call does not dispatch the event to the instance.
+You will receive back the list of events that you submitted, with an
+updated ``code`` and ``status`` indicating their level of success.
 
-Normal response codes: 200
+Normal response codes: 200, 207
+
+A 200 will be returned if all events succeeded, 207 will be returned
+if some events could not be processed. The ``code`` attribute for the
+event will explain further what went wrong.
 
 Error response codes: badRequest(400), unauthorized(401), forbidden(403),
 itemNotFound(404)
+
 Request
 -------
 
@@ -30,12 +45,12 @@ Request
 
   - tenant_id: tenant_id
   - events: events
-  - name: name
-  - tag: tag
+  - name: event_name
   - server_uuid: server_uuid
-  - status: status
+  - status: event_status
+  - tag: event_tag
 
-**Example Run Events: JSON request**
+**Example Run Events**
 
 .. literalinclude:: ../../doc/api_samples/os-server-external-events/event-create-req.json
    :language: javascript
@@ -47,13 +62,12 @@ Response
 
   - events: events
   - code: code
-  - name: name
+  - name: event_name
   - server_uuid: server_uuid
-  - status: status
-  - tag: tag
+  - status: event_status
+  - tag: event_tag
 
-**Example Run Events: JSON response**
+**Example Run Events**
 
 .. literalinclude:: ../../doc/api_samples/os-server-external-events/event-create-resp.json
    :language: javascript
-
diff --git a/api-ref/source/os-services.inc b/api-ref/source/os-services.inc
index c18ae56bbc8d..4da3bb2c0440 100644
--- a/api-ref/source/os-services.inc
+++ b/api-ref/source/os-services.inc
@@ -45,7 +45,7 @@ Response
   - disabled_reason: disabled_reason
   - host: host
   - state: service_state
-  - status: status
+  - status: service_status
   - updated_at: updated
   - forced_down: forced_down
   - zone: OS-EXT-AZ:availability_zone
@@ -90,7 +90,7 @@ Response
   - service: service
   - binary: binary
   - host: host
-  - status: status
+  - status: service_status
 
 **Example Enable Scheduling For A Compute Service: JSON response**
 
@@ -132,7 +132,7 @@ Response
   - service: service
   - binary: binary
   - host: host
-  - status: status
+  - status: service_status
 
 **Example Disable Scheduling For A Compute Service: JSON response**
 
@@ -176,7 +176,7 @@ Response
   - binary: binary
   - disabled_reason: disabled_reason
   - host: host
-  - status: status
+  - status: service_status
 
 **Example Log Disabled Compute Service Information: JSON response**
 
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 08fd0df2658e..5ba09d5a7b98 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -859,7 +859,12 @@ cidr:
   type: string
 code:
   description: |
-    The HTTP response code for the event.
+    The HTTP response code for the event. The following codes are currently used:
+
+      * 200 - successfully submitted event
+      * 404 - the instance specified by ``server_uuid`` was not found
+      * 422 - no host was found for the server specified by ``server_uuid``,
+         so there is no route to this server.
   in: body
   required: true
   type: string
@@ -1011,6 +1016,26 @@ evacuate:
   in: body
   required: true
   type: string
+event_name:
+  description: |
+    The event name. A valid value is ``network-changed``, ``network-vif-plugged``,
+    ``network-vif-unplugged``, or ``network-vif-deleted``.
+  in: body
+  required: true
+  type: string
+event_status:
+  description: |
+    The event status. A valid value is ``failed``, ``completed``, or ``in-progress``.
+    Default is ``completed``.
+  in: body
+  required: false
+  type: string
+event_tag:
+  description: |
+    A string value that identifies the event.
+  in: body
+  required: false
+  type: string
 events:
   description: |
     The action.
@@ -1607,13 +1632,6 @@ name_10:
   in: body
   required: true
   type: string
-name_2:
-  description: |
-    The event name. A valid value is ``network- changed``, ``network- vif-plugged``,
-    ``network-vif-unplugged``, or ``network-vif- deleted``.
-  in: body
-  required: true
-  type: string
 name_3:
   description: |
     The name to associate with the keypair.
@@ -2152,6 +2170,12 @@ service_state:
   type: string
   description: |
     The state of the service. One of ``up`` or ``down``.
+service_status:
+  in: body
+  required: true
+  type: string
+  description: |
+    The status of the service. One of ``enabled`` or ``disabled``.
 shelve:
   description: |
     The action.
@@ -2195,13 +2219,6 @@ source_type:
   in: body
   required: true
   type: string
-status:
-  description: |
-    The event status. A valid value is ``failed``, ``completed``, or ``in-progress``.
-    Default is ``completed``.
-  in: body
-  required: false
-  type: string
 server_status:
   description: |
     The server status.
@@ -2214,12 +2231,6 @@ suspend:
   in: body
   required: true
   type: string
-tag:
-  description: |
-    A string value that identifies the event.
-  in: body
-  required: false
-  type: string
 tenant_id_body:
   description: |
     The UUID of the tenant this server is owned by.