diff --git a/website/source/docs/agent/http.html.markdown b/website/source/docs/agent/http.html.markdown
index 88e555c822..7ae4988d81 100644
--- a/website/source/docs/agent/http.html.markdown
+++ b/website/source/docs/agent/http.html.markdown
@@ -14,14 +14,14 @@ versioned to enable changes without breaking backwards compatibility.
All endpoints fall into one of several categories:
-* kv - Key/Value store
-* agent - Agent control
-* catalog - Manages nodes and services
-* health - Manages health checks
-* session - Session manipulation
-* acl - ACL creations and management
-* event - User Events
-* status - Consul system status
+* [kv][kv] - Key/Value store
+* [agent][agent] - Agent control
+* [catalog][catalog] - Manages nodes and services
+* [health][health] - Manages health checks
+* [session][session] - Session manipulation
+* [acl][acl] - ACL creations and management
+* [event][event] - User Events
+* [status][status] - Consul system status
* internal - Internal APIs. Purposely undocumented, subject to change.
Each of the categories and their respective endpoints are documented below.
@@ -97,7 +97,7 @@ configuration option. However, the token can also be specified per-request
by using the "?token=" query parameter. This will take precedence over the
default token.
-## KV
+## KV
The KV endpoint is used to expose a simple key/value store. This can be used
to store service configurations or other meta data in a simple way. It has only
@@ -213,7 +213,7 @@ keys sharing a prefix. If the "?recurse" query parameter is provided,
then all keys with the prefix are deleted, otherwise only the specified
key.
-## Agent
+## Agent
The Agent endpoints are used to interact with a local Consul agent. Usually,
services and checks are registered with an agent, which then takes on the
@@ -223,21 +223,21 @@ msgpack RPC protocol.
The following endpoints are supported:
-* /v1/agent/checks : Returns the checks the local agent is managing
-* /v1/agent/services : Returns the services local agent is managing
-* /v1/agent/members : Returns the members as seen by the local serf agent
-* /v1/agent/self : Returns the local node configuration
-* /v1/agent/join/\
: Trigger local agent to join a node
-* /v1/agent/force-leave/\: Force remove node
-* /v1/agent/check/register : Registers a new local check
-* /v1/agent/check/deregister/\ : Deregister a local check
-* /v1/agent/check/pass/\ : Mark a local test as passing
-* /v1/agent/check/warn/\ : Mark a local test as warning
-* /v1/agent/check/fail/\ : Mark a local test as critical
-* /v1/agent/service/register : Registers a new local service
-* /v1/agent/service/deregister/\ : Deregister a local service
+* [`/v1/agent/checks`](#agent_checks) : Returns the checks the local agent is managing
+* [`/v1/agent/services`](#agent_services) : Returns the services local agent is managing
+* [`/v1/agent/members`](#agent_members) : Returns the members as seen by the local serf agent
+* [`/v1/agent/self`](#agent_self) : Returns the local node configuration
+* [`/v1/agent/join/\`](#agent_join) : Trigger local agent to join a node
+* [`/v1/agent/force-leave/\: Force remove node
+* [`/v1/agent/check/register`](#agent_check_register) : Registers a new local check
+* [`/v1/agent/check/deregister/\`](#agent_check_deregister) : Deregister a local check
+* [`/v1/agent/check/pass/\`](#agent_check_pass) : Mark a local test as passing
+* [`/v1/agent/check/warn/\`](#agent_check_warn) : Mark a local test as warning
+* [`/v1/agent/check/fail/\`](#agent_check_fail) : Mark a local test as critical
+* [`/v1/agent/service/register`](#agent_service_register) : Registers a new local service
+* [`/v1/agent/service/deregister/\`](#agent_service_deregister) : Deregister a local service
-### /v1/agent/checks
+### /v1/agent/checks
This endpoint is used to return the all the checks that are registered with
the local agent. These checks were either provided through configuration files,
@@ -263,7 +263,7 @@ This endpoint is hit with a GET and returns a JSON body like this:
}
```
-### /v1/agent/services
+### /v1/agent/services
This endpoint is used to return the all the services that are registered with
the local agent. These services were either provided through configuration files,
@@ -285,7 +285,7 @@ This endpoint is hit with a GET and returns a JSON body like this:
}
```
-### /v1/agent/members
+### /v1/agent/members
This endpoint is hit with a GET and returns the members the agent sees in the
cluster gossip pool. Due to the nature of gossip, this is eventually consistent
@@ -320,7 +320,7 @@ This endpoint returns a JSON body like:
]
```
-### /v1/agent/self
+### /v1/agent/self
This endpoint is used to return configuration of the local agent and member information.
@@ -388,7 +388,7 @@ It returns a JSON body like this:
}
```
-### /v1/agent/join/\
+### /v1/agent/join/\
This endpoint is hit with a GET and is used to instruct the agent to attempt to
connect to a given address. For agents running in server mode, providing a "?wan=1"
@@ -396,7 +396,7 @@ query parameter causes the agent to attempt to join using the WAN pool.
The endpoint returns 200 on successful join.
-### /v1/agent/force-leave/\
+### /v1/agent/force-leave/\
This endpoint is hit with a GET and is used to instructs the agent to force a node into the left state.
If a node fails unexpectedly, then it will be in a "failed" state. Once in this state, Consul will
@@ -405,7 +405,7 @@ cleaned up. Forcing a node into the left state allows its old entries to be remo
The endpoint always returns 200.
-### /v1/agent/check/register
+### /v1/agent/check/register
The register endpoint is used to add a new check to the local agent.
There is more documentation on checks [here](/docs/agent/checks.html).
@@ -439,7 +439,7 @@ the state of the check.
The return code is 200 on success.
-### /v1/agent/check/deregister/\
+### /v1/agent/check/deregister/\
The deregister endpoint is used to remove a check from the local agent.
The CheckID must be passed after the slash. The agent will take care
@@ -447,7 +447,7 @@ of deregistering the check with the Catalog.
The return code is 200 on success.
-### /v1/agent/check/pass/\
+### /v1/agent/check/pass/\
This endpoint is used with a check that is of the [TTL type](/docs/agent/checks.html).
When this endpoint is accessed via a GET, the status of the check is set to "passing",
@@ -458,7 +458,7 @@ the status of the check. This should be human readable for operators.
The return code is 200 on success.
-### /v1/agent/check/warn/\
+### /v1/agent/check/warn/\
This endpoint is used with a check that is of the [TTL type](/docs/agent/checks.html).
When this endpoint is accessed via a GET, the status of the check is set to "warning",
@@ -469,7 +469,7 @@ the status of the check. This should be human readable for operators.
The return code is 200 on success.
-### /v1/agent/check/fail/\
+### /v1/agent/check/fail/\
This endpoint is used with a check that is of the [TTL type](/docs/agent/checks.html).
When this endpoint is accessed via a GET, the status of the check is set to "critical",
@@ -480,7 +480,7 @@ the status of the check. This should be human readable for operators.
The return code is 200 on success.
-### /v1/agent/service/register
+### /v1/agent/service/register
The register endpoint is used to add a new service to the local agent.
There is more documentation on services [here](/docs/agent/services.html).
@@ -516,7 +516,7 @@ The created check will be named "service:\".
The return code is 200 on success.
-### /v1/agent/service/deregister/\
+### /v1/agent/service/deregister/\
The deregister endpoint is used to remove a service from the local agent.
The ServiceID must be passed after the slash. The agent will take care
@@ -525,25 +525,25 @@ check, that is also deregistered.
The return code is 200 on success.
-## Catalog
+## Catalog
The Catalog is the endpoint used to register and deregister nodes,
services, and checks. It also provides a number of query endpoints.
The following endpoints are supported:
-* /v1/catalog/register : Registers a new node, service, or check
-* /v1/catalog/deregister : Deregisters a node, service, or check
-* /v1/catalog/datacenters : Lists known datacenters
-* /v1/catalog/nodes : Lists nodes in a given DC
-* /v1/catalog/services : Lists services in a given DC
-* /v1/catalog/service/\ : Lists the nodes in a given service
-* /v1/catalog/node/\ : Lists the services provided by a node
+* [`/v1/catalog/register`](#catalog_register) : Registers a new node, service, or check
+* [`/v1/catalog/deregister`](#catalog_deregister) : Deregisters a node, service, or check
+* [`/v1/catalog/datacenters`](#catalog_datacenters) : Lists known datacenters
+* [`/v1/catalog/nodes`](#catalog_nodes) : Lists nodes in a given DC
+* [`/v1/catalog/services`](#catalog_services) : Lists services in a given DC
+* [`/v1/catalog/service/\`](#catalog_service) : Lists the nodes in a given service
+* [`/v1/catalog/node/\`](#catalog_nodes) : Lists the services provided by a node
The last 4 endpoints of the catalog support blocking queries and
consistency modes.
-### /v1/catalog/register
+### /v1/catalog/register
The register endpoint is a low level mechanism for directly registering
or updating entries in the catalog. It is usually recommended to use
@@ -604,7 +604,7 @@ and visa-versa. They can be provided or omitted at will.
If the API call succeeds a 200 status code is returned.
-### /v1/catalog/deregister
+### /v1/catalog/deregister
The deregister endpoint is a low level mechanism for direclty removing
entries in the catalog. It is usually recommended to use the agent local
@@ -646,7 +646,7 @@ service along with its associated health check (if any) is removed.
If the API call succeeds a 200 status code is returned.
-### /v1/catalog/datacenters
+### /v1/catalog/datacenters
This endpoint is hit with a GET and is used to return all the
datacenters that are known by the Consul server.
@@ -661,7 +661,7 @@ This endpoint does not require a cluster leader, and as such
will succeed even during an availability outage. It can thus be
a simple check to see if any Consul servers are routable.
-### /v1/catalog/nodes
+### /v1/catalog/nodes
This endpoint is hit with a GET and returns the nodes known
about in a given DC. By default the datacenter of the agent is queried,
@@ -684,7 +684,7 @@ It returns a JSON body like this:
This endpoint supports blocking queries and all consistency modes.
-### /v1/catalog/services
+### /v1/catalog/services
This endpoint is hit with a GET and returns the services known
about in a given DC. By default the datacenter of the agent is queried,
@@ -708,7 +708,7 @@ provides all the known tags for a given service.
This endpoint supports blocking queries and all consistency modes.
-### /v1/catalog/service/\
+### /v1/catalog/service/\
This endpoint is hit with a GET and returns the nodes providing a service
in a given DC. By default the datacenter of the agent is queried,
@@ -735,7 +735,7 @@ It returns a JSON body like this:
This endpoint supports blocking queries and all consistency modes.
-### /v1/catalog/node/\
+### /v1/catalog/node/\
This endpoint is hit with a GET and returns the node provided services.
By default the datacenter of the agent is queried,
@@ -771,7 +771,7 @@ It returns a JSON body like this:
This endpoint supports blocking queries and all consistency modes.
-## Health
+## Health
The Health used to query health related information. It is provided separately
from the Catalog, since users may prefer to not use the health checking mechanisms
@@ -779,14 +779,14 @@ as they are totally optional. Additionally, some of the query results from the H
The following endpoints are supported:
-* /v1/health/node/\: Returns the health info of a node
-* /v1/health/checks/\: Returns the checks of a service
-* /v1/health/service/\: Returns the nodes and health info of a service
-* /v1/health/state/\: Returns the checks in a given state
+* [`/v1/health/node/\`](#health_node): Returns the health info of a node
+* [`/v1/health/checks/\`](#health_checks): Returns the checks of a service
+* [`/v1/health/service/\`](#health_service): Returns the nodes and health info of a service
+* [`/v1/health/state/\`](#health_state): Returns the checks in a given state
All of the health endpoints supports blocking queries and all consistency modes.
-### /v1/health/node/\
+### /v1/health/node/\
This endpoint is hit with a GET and returns the node specific checks known.
By default the datacenter of the agent is queried,
@@ -829,7 +829,7 @@ changed to "critical".
This endpoint supports blocking queries and all consistency modes.
-### /v1/health/checks/\
+### /v1/health/checks/\
This endpoint is hit with a GET and returns the checks associated with
a service in a given datacenter.
@@ -856,7 +856,7 @@ It returns a JSON body like this:
This endpoint supports blocking queries and all consistency modes.
-### /v1/health/service/\
+### /v1/health/service/\
This endpoint is hit with a GET and returns the service nodes providing
a given service in a given datacenter.
@@ -922,7 +922,7 @@ It returns a JSON body like this:
This endpoint supports blocking queries and all consistency modes.
-### /v1/health/state/\
+### /v1/health/state/\
This endpoint is hit with a GET and returns the checks in a specific
state for a given datacenter. By default the datacenter of the agent is queried,
@@ -961,20 +961,20 @@ It returns a JSON body like this:
This endpoint supports blocking queries and all consistency modes.
-## Session
+## Session
The Session endpoints are used to create, destroy and query sessions.
The following endpoints are supported:
-* /v1/session/create: Creates a new session
-* /v1/session/destroy/\: Destroys a given session
-* /v1/session/info/\: Queries a given session
-* /v1/session/node/\: Lists sessions belonging to a node
-* /v1/session/list: Lists all the active sessions
+* [`/v1/session/create`](#session_create): Creates a new session
+* [`/v1/session/destroy/\`](#session_destroy): Destroys a given session
+* [`/v1/session/info/\`](#session_info): Queries a given session
+* [`/v1/session/node/\`](#session_node): Lists sessions belonging to a node
+* [`/v1/session/list`](#session_list): Lists all the active sessions
All of the read session endpoints supports blocking queries and all consistency modes.
-### /v1/session/create
+### /v1/session/create
The create endpoint is used to initialize a new session.
There is more documentation on sessions [here](/docs/internals/sessions.html).
@@ -1020,7 +1020,7 @@ The return code is 200 on success, along with a body like:
This is used to provide the ID of the newly created session.
-### /v1/session/destroy/\
+### /v1/session/destroy/\
The destroy endpoint is hit with a PUT and destroys the given session.
By default the local datacenter is used, but the "?dc=" query parameter
@@ -1029,7 +1029,7 @@ be provided after the slash.
The return code is 200 on success.
-### /v1/session/info/\
+### /v1/session/info/\
This endpoint is hit with a GET and returns the session information
by ID within a given datacenter. By default the datacenter of the agent is queried,
@@ -1055,7 +1055,7 @@ It returns a JSON body like this:
If the session is not found, null is returned instead of a JSON list.
This endpoint supports blocking queries and all consistency modes.
-### /v1/session/node/\
+### /v1/session/node/\
This endpoint is hit with a GET and returns the active sessions
for a given node and datacenter. By default the datacenter of the agent is queried,
@@ -1081,7 +1081,7 @@ It returns a JSON body like this:
This endpoint supports blocking queries and all consistency modes.
-### /v1/session/list
+### /v1/session/list
This endpoint is hit with a GET and returns the active sessions
for a given datacenter. By default the datacenter of the agent is queried,
@@ -1106,19 +1106,19 @@ It returns a JSON body like this:
This endpoint supports blocking queries and all consistency modes.
-## ACL
+## ACL
The ACL endpoints are used to create, update, destroy and query ACL tokens.
The following endpoints are supported:
-* /v1/acl/create: Creates a new token with policy
-* /v1/acl/update: Update the policy of a token
-* /v1/acl/destroy/\: Destroys a given token
-* /v1/acl/info/\: Queries the policy of a given token
-* /v1/acl/clone/\: Creates a new token by cloning an existing token
-* /v1/acl/list: Lists all the active tokens
+* [`/v1/acl/create`](#acl_create): Creates a new token with policy
+* [`/v1/acl/update`](#acl_update): Update the policy of a token
+* [`/v1/acl/destroy/\`](#acl_destroy): Destroys a given token
+* [`/v1/acl/info/\`](#acl_info): Queries the policy of a given token
+* [`/v1/acl/clone/\`](#acl_clone): Creates a new token by cloning an existing token
+* [`/v1/acl/list`](#acl_list): Lists all the active tokens
-### /v1/acl/create
+### /v1/acl/create
The create endpoint is used to make a new token. A token has a name,
type, and a set of ACL rules. The name is opaque to Consul, and type
@@ -1159,7 +1159,7 @@ The return code is 200 on success, along with a body like:
This is used to provide the ID of the newly created ACL token.
-### /v1/acl/update
+### /v1/acl/update
The update endpoint is used to modify the policy for a given
ACL token. It is very similar to the create endpoint, however
@@ -1189,7 +1189,7 @@ The format of `Rules` is [documented here](/docs/internals/acl.html).
The return code is 200 on success.
-### /v1/acl/destroy/\
+### /v1/acl/destroy/\
The destroy endpoint is hit with a PUT and destroys the given ACL token.
The request is automatically routed to the authoritative ACL datacenter.
@@ -1198,7 +1198,7 @@ to the endpoint must be made with a management token.
The return code is 200 on success.
-### /v1/acl/info/\
+### /v1/acl/info/\
This endpoint is hit with a GET and returns the token information
by ID. All requests are routed to the authoritative ACL datacenter
@@ -1221,7 +1221,7 @@ It returns a JSON body like this:
If the session is not found, null is returned instead of a JSON list.
-### /v1/acl/clone/\
+### /v1/acl/clone/\
The clone endpoint is hit with a PUT and returns a token ID that
is cloned from an existing token. This allows a token to serve
@@ -1239,7 +1239,7 @@ The return code is 200 on success, along with a body like:
This is used to provide the ID of the newly created ACL token.
-### /v1/acl/list
+### /v1/acl/list
The list endpoint is hit with a GET and lists all the active
ACL tokens. This is a privileged endpoint, and requires a
@@ -1261,17 +1261,17 @@ It returns a JSON body like this:
]
```
-## Event
+## Event
The Event endpoints are used to fire new events and to query the available
events.
The following endpoints are supported:
-* /v1/event/fire/\: Fires a new user event
-* /v1/event/list: Lists the most recent events an agent has seen.
+* [`/v1/event/fire/\`](#event_fire): Fires a new user event
+* [`/v1/event/list`](#event_list): Lists the most recent events an agent has seen.
-### /v1/event/fire/\
+### /v1/event/fire/\
The fire endpoint is used to trigger a new user event. A user event
needs a name, and optionally takes a number of parameters.
@@ -1305,7 +1305,7 @@ The return code is 200 on success, along with a body like:
This is used to provide the ID of the newly fired event.
-### /v1/event/list
+### /v1/event/list
This endpoint is hit with a GET and returns the most recent
events known by the agent. As a consequence of how the
@@ -1357,7 +1357,7 @@ It returns a JSON body like this:
]
```
-## Status
+## Status
The Status endpoints are used to get information about the status
of the Consul cluster. This are generally very low level, and not really
@@ -1365,10 +1365,10 @@ useful for clients.
The following endpoints are supported:
-* /v1/status/leader : Returns the current Raft leader
-* /v1/status/peers : Returns the current Raft peer set
+* [`/v1/status/leader`](#status_leader) : Returns the current Raft leader
+* [`/v1/status/peers`](#status_peers) : Returns the current Raft peer set
-### /v1/status/leader
+### /v1/status/leader
This endpoint is used to get the Raft leader for the datacenter
the agent is running in. It returns only an address like:
@@ -1377,7 +1377,7 @@ the agent is running in. It returns only an address like:
"10.1.10.12:8300"
```
-### /v1/status/peers
+### /v1/status/peers
This endpoint is used to get the Raft peers for the datacenter
the agent is running in. It returns a list of addresses like:
@@ -1389,3 +1389,12 @@ the agent is running in. It returns a list of addresses like:
"10.1.10.10:8300"
]
```
+
+[kv]: #kv
+[agent]: #agent
+[catalog]: #catalog
+[health]: #health
+[session]: #session
+[acl]: #acl
+[event]: #event
+[status]: #status