diff --git a/website/source/docs/agent/http.html.markdown b/website/source/docs/agent/http.html.markdown
index aeb0537922..69f6fe1311 100644
--- a/website/source/docs/agent/http.html.markdown
+++ b/website/source/docs/agent/http.html.markdown
@@ -3,96 +3,93 @@ layout: "docs"
 page_title: "HTTP API"
 sidebar_current: "docs-agent-http"
 description: |-
-  The main interface to Consul is a RESTful HTTP API. The API can be used for CRUD for nodes, services, checks, and configuration. The endpoints are versioned to enable changes without breaking backwards compatibility.
+  The main interface to Consul is a RESTful HTTP API. The API can be used to perform CRUD operations on nodes, services, checks, configuration, and more. The endpoints are versioned to enable changes without breaking backwards compatibility.
 ---
 
 # HTTP API
 
-The main interface to Consul is a RESTful HTTP API. The API can be
-used for CRUD for nodes, services, checks, and configuration. The endpoints are
-versioned to enable changes without breaking backwards compatibility.
+The main interface to Consul is a RESTful HTTP API. The API can be used to perform CRUD
+operations on nodes, services, checks, configuration, and more. The endpoints are versioned
+to enable changes without breaking backwards compatibility.
 
-All endpoints fall into one of several categories:
+Each endpoint manages a different aspect of Consul:
 
 * [kv](http/kv.html) - Key/Value store
-* [agent](http/agent.html) - Agent control
-* [catalog](http/catalog.html) - Manages nodes and services
-* [health](http/health.html) - Manages health checks
-* [session](http/session.html) - Session manipulation
-* [acl](http/acl.html) - ACL creations and management
+* [agent](http/agent.html) - Consul Agent
+* [catalog](http/catalog.html) - Modes and services
+* [health](http/health.html) - Health checks
+* [session](http/session.html) - Sessions
+* [acl](http/acl.html) - Access Control Lists
 * [event](http/event.html) - User Events
 * [status](http/status.html) - Consul system status
 * internal - Internal APIs. Purposely undocumented, subject to change.
 
-Each of the categories and their respective endpoints are documented below.
+Each of these is documented in detail at the links above.
 
 ## Blocking Queries
 
 Certain endpoints support a feature called a "blocking query." A blocking query
-is used to wait for a change to potentially take place using long polling.
+is used to wait for a potential change using long polling.
 
-Queries that support this will mention it specifically, however the use of this
-feature is the same for all. If supported, the query will set an HTTP header
-"X-Consul-Index". This is an opaque handle that the client will use.
+Not all endpoints support blocking, but those that do are clearly designated in the
+documentations.  Any endpoint that supports blocking will also set the HTTP header
+`X-Consul-Index`, a unique identifier representing the current state of this
+requested resource.  When again requesting this resource, the client can set the `index`
+query string parameter to the value of "X-Consul-Index", indicating that it wishes to wait
+for any changes subsequent to that index.
 
-To cause a query to block, the query parameters "?wait=\<interval\>&index=\<idx\>" are added
-to a request. The "?wait=" query parameter limits how long the query will potentially
-block for. It not set, it will default to 10 minutes. It can be specified in the form of
-"10s" or "5m", which is 10 seconds or 5 minutes respectively. The "?index=" parameter is an
-opaque handle, which is used by Consul to detect changes. The  "X-Consul-Index" header for a
-query provides this value, and can be used to wait for changes since the query was run.
+In addition to `index`, endpoints that support blocking will also honor a `wait`
+parameter specifying a maximum duration for the blocking request. It not set, it will
+default to 10 minutes. This value can be specified in the form of "10s" or "5m" (i.e.,
+10 seconds or 5 minutes, respectively).
 
-When provided, Consul blocks sending a response until there is an update that
-could have cause the output to change, and thus advancing the index. A critical
-note is that when the query returns there is **no guarantee** of a change. It is
-possible that the timeout was reached, or that there was an idempotent write that
-does not affect the result.
+A critical note is that the return of a blocking request is **no guarantee** of a change. It
+is possible that the timeout was reached or that there was an idempotent write that does
+not affect the result of the query.
 
 ## Consistency Modes
 
-Most of the read query endpoints support multiple levels of consistency.
-These are to provide a tuning knob that clients can be used to find a happy
-medium that best matches their needs.
+Most of the read query endpoints support multiple levels of consistency. Since no policy will
+suit all clients' needs, these consistency modes allow the user to have the ultimate say in
+how to balance the trade-offs inherent in a distributed system.
 
 The three read modes are:
 
-* default - If not specified, this mode is used. It is strongly consistent
-  in almost all cases. However, there is a small window in which an new
-  leader may be elected, and the old leader may service stale values. The
-  trade off is fast reads, but potentially stale values. This condition is
-  hard to trigger, and most clients should not need to worry about the stale read.
-  This only applies to reads, and a split-brain is not possible on writes.
+* default - If not specified, the default is strongly consistent in almost all cases. However,
+  there is a small window in which a new leader may be elected during which the old leader may
+  service stale values. The trade-off is fast reads but potentially stale values. The condition
+  resulting in stale reads is hard to trigger, and most clients should not need to worry about
+  this case.  Also, note that this race condition only applies to reads, not writes.
 
 * consistent - This mode is strongly consistent without caveats. It requires
   that a leader verify with a quorum of peers that it is still leader. This
-  introduces an additional round-trip to all server nodes. The trade off is
-  always consistent reads, but increased latency due to an extra round trip.
-  Most clients should not use this unless they cannot tolerate a stale read.
+  introduces an additional round-trip to all server nodes. The trade-off is
+  increased latency due to an extra round trip. Most clients should not use this
+  unless they cannot tolerate a stale read.
 
-* stale - This mode allows any server to service the read, regardless of if
-  it is the leader. This means reads can be arbitrarily stale, but are generally
-  within 50 milliseconds of the leader. The trade off is very fast and scalable
-  reads but values will be stale. This mode allows reads without a leader, meaning
-  a cluster that is unavailable will still be able to respond.
+* stale - This mode allows any server to service the read regardless of if
+  it is the leader. This means reads can be arbitrarily stale but are generally
+  consistent to within 50 milliseconds of the leader. The trade-off is very fast and
+  scalable reads with a higher likelihood of stale values. This mode allows reads without
+  a leader, meaning a cluster that is unavailable will still be able to respond to queries.
 
-To switch these modes, either the "?stale" or "?consistent" query parameters
-are provided. It is an error to provide both.
+To switch these modes, either the `stale` or `consistent` query parameters
+should be provided on requests. It is an error to provide both.
 
-To support bounding how stale data is, there is an "X-Consul-LastContact"
-which is the last time a server was contacted by the leader node in
-milliseconds. The "X-Consul-KnownLeader" also indicates if there is a known
-leader. These can be used to gauge if a stale read should be used.
+To support bounding the acceptable staleness of data, responses provide the `X-Consul-LastContact`
+header containing the time in milliseconds that a server was last contacted by the leader node.
+The `X-Consul-KnownLeader` header also indicates if there is a known leader. These can be used
+by clients to gauge the staleness of a result and take appropriate action.
 
 ## Formatted JSON Output
 
-By default, the output of all HTTP API requests return minimized JSON with all
-whitespace removed.  By adding "?pretty" to the HTTP request URL,
-formatted JSON will be returned.
+By default, the output of all HTTP API requests is minimized JSON.  If the client passes `pretty`
+on the query string, formatted JSON will be returned.
 
 ## ACLs
 
 Several endpoints in Consul use or require ACL tokens to operate. An agent
 can be configured to use a default token in requests using the `acl_token`
 configuration option. However, the token can also be specified per-request
-by using the "?token=" query parameter. This will take precedence over the
+by using the `token` query parameter. This will take precedent over the
 default token.