1---
2layout: api
3page_title: Agent - HTTP API
4sidebar_current: api-agent
5description: |-
6  The /agent endpoints interact with the local Consul agent to register
7  services, checks, list members, and more.
8---
9
10# Agent HTTP API
11
12The `/agent` endpoints are used to interact with the local Consul agent.
13Usually, services and checks are registered with an agent which then takes on
14the burden of keeping that data synchronized with the cluster. For example, the
15agent registers services and checks with the Catalog and performs
16[anti-entropy](/docs/internals/anti-entropy.html) to recover from outages.
17
18In addition to these endpoints, additional endpoints are grouped in the
19navigation for `Checks` and `Services`.
20
21## List Members
22
23This endpoint returns the members the agent sees in the cluster gossip pool. Due
24to the nature of gossip, this is eventually consistent: the results may differ
25by agent. The strongly consistent view of nodes is instead provided by
26`/v1/catalog/nodes`.
27
28| Method | Path                         | Produces                   |
29| ------ | ---------------------------- | -------------------------- |
30| `GET`  | `/agent/members`             | `application/json`         |
31
32The table below shows this endpoint's support for
33[blocking queries](/api/index.html#blocking-queries),
34[consistency modes](/api/index.html#consistency-modes),
35[agent caching](/api/index.html#agent-caching), and
36[required ACLs](/api/index.html#acls).
37
38| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
39| ---------------- | ----------------- | ------------- | ------------ |
40| `NO`             | `none`            | `none`        | `node:read`  |
41
42### Parameters
43
44- `wan` `(bool: false)` - Specifies to list WAN members instead of the LAN
45  members (which is the default). This is only eligible for agents running in
46  **server mode**. This is specified as part of the URL as a query parameter.
47
48- `segment` `(string: "")` - (Enterprise-only) Specifies the segment to list members for.
49  If left blank, this will query for the default segment when connecting to a server and
50  the agent's own segment when connecting to a client (clients can only be part of one
51  network segment). When querying a server, setting this to the special string `_all`
52  will show members in all segments.
53
54### Sample Request
55
56```text
57$ curl \
58    http://127.0.0.1:8500/v1/agent/members
59```
60
61### Sample Response
62
63```json
64[
65  {
66    "Name": "foobar",
67    "Addr": "10.1.10.12",
68    "Port": 8301,
69    "Tags": {
70      "bootstrap": "1",
71      "dc": "dc1",
72      "port": "8300",
73      "role": "consul"
74    },
75    "Status": 1,
76    "ProtocolMin": 1,
77    "ProtocolMax": 2,
78    "ProtocolCur": 2,
79    "DelegateMin": 1,
80    "DelegateMax": 3,
81    "DelegateCur": 3
82  }
83]
84```
85
86## Read Configuration
87
88This endpoint returns the configuration and member information of the local
89agent. The `Config` element contains a subset of the configuration and its
90format will not change in a backwards incompatible way between releases.
91`DebugConfig` contains the full runtime configuration but its format is subject
92to change without notice or deprecation.
93
94| Method | Path                         | Produces                   |
95| ------ | ---------------------------- | -------------------------- |
96| `GET`  | `/agent/self`                | `application/json`         |
97
98The table below shows this endpoint's support for
99[blocking queries](/api/index.html#blocking-queries),
100[consistency modes](/api/index.html#consistency-modes),
101[agent caching](/api/index.html#agent-caching), and
102[required ACLs](/api/index.html#acls).
103
104| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
105| ---------------- | ----------------- | ------------- | ------------ |
106| `NO`             | `none`            | `none`        | `agent:read` |
107
108### Sample Request
109
110```text
111$ curl \
112    http://127.0.0.1:8500/v1/agent/self
113```
114
115### Sample Response
116
117```json
118{
119  "Config": {
120    "Datacenter": "dc1",
121    "NodeName": "foobar",
122    "NodeID": "9d754d17-d864-b1d3-e758-f3fe25a9874f",
123    "Server": true,
124    "Revision": "deadbeef",
125    "Version": "1.0.0"
126  },
127  "DebugConfig": {
128    ... full runtime configuration ...
129    ... format subject to change ...
130  },
131  "Coord": {
132    "Adjustment": 0,
133    "Error": 1.5,
134    "Vec": [0,0,0,0,0,0,0,0]
135  },
136  "Member": {
137    "Name": "foobar",
138    "Addr": "10.1.10.12",
139    "Port": 8301,
140    "Tags": {
141      "bootstrap": "1",
142      "dc": "dc1",
143      "id": "40e4a748-2192-161a-0510-9bf59fe950b5",
144      "port": "8300",
145      "role": "consul",
146      "vsn": "1",
147      "vsn_max": "1",
148      "vsn_min": "1"
149    },
150    "Status": 1,
151    "ProtocolMin": 1,
152    "ProtocolMax": 2,
153    "ProtocolCur": 2,
154    "DelegateMin": 2,
155    "DelegateMax": 4,
156    "DelegateCur": 4
157  },
158  "Meta": {
159    "instance_type": "i2.xlarge",
160    "os_version": "ubuntu_16.04"
161  }
162}
163```
164
165## Reload Agent
166
167This endpoint instructs the agent to reload its configuration. Any errors
168encountered during this process are returned.
169
170Not all configuration options are reloadable. See the
171[Reloadable Configuration](/docs/agent/options.html#reloadable-configuration)
172section on the agent options page for details on which options are supported.
173
174| Method | Path                         | Produces                   |
175| ------ | ---------------------------- | -------------------------- |
176| `PUT`  | `/agent/reload`              | `application/json`         |
177
178The table below shows this endpoint's support for
179[blocking queries](/api/index.html#blocking-queries),
180[consistency modes](/api/index.html#consistency-modes),
181[agent caching](/api/index.html#agent-caching), and
182[required ACLs](/api/index.html#acls).
183
184| Blocking Queries | Consistency Modes | Agent Caching | ACL Required  |
185| ---------------- | ----------------- | ------------- | ------------- |
186| `NO`             | `none`            | `none`        | `agent:write` |
187
188### Sample Request
189
190```text
191$ curl \
192    --request PUT \
193    http://127.0.0.1:8500/v1/agent/reload
194```
195
196## Enable Maintenance Mode
197
198This endpoint places the agent into "maintenance mode". During maintenance mode,
199the node will be marked as unavailable and will not be present in DNS or API
200queries. This API call is idempotent.
201
202Maintenance mode is persistent and will be automatically restored on agent
203restart.
204
205| Method | Path                         | Produces                   |
206| ------ | ---------------------------- | -------------------------- |
207| `PUT`  | `/agent/maintenance`         | `application/json`         |
208
209The table below shows this endpoint's support for
210[blocking queries](/api/index.html#blocking-queries),
211[consistency modes](/api/index.html#consistency-modes),
212[agent caching](/api/index.html#agent-caching), and
213[required ACLs](/api/index.html#acls).
214
215| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
216| ---------------- | ----------------- | ------------- | ------------ |
217| `NO`             | `none`            | `none`        | `node:write` |
218
219### Parameters
220
221- `enable` `(bool: <required>)` - Specifies whether to enable or disable
222  maintenance mode. This is specified as part of the URL as a query string
223  parameter.
224
225- `reason` `(string: "")` - Specifies a text string explaining the reason for
226  placing the node into maintenance mode. This is simply to aid human operators.
227  If no reason is provided, a default value will be used instead. This is
228  specified as part of the URL as a query string parameter, and, as such, must
229  be URI-encoded.
230
231### Sample Request
232
233```text
234$ curl \
235    --request PUT \
236    http://127.0.0.1:8500/v1/agent/maintenance?enable=true&reason=For+API+docs
237```
238
239## View Metrics
240
241This endpoint will dump the metrics for the most recent finished interval.
242For more information about metrics, see the [telemetry](/docs/agent/telemetry.html)
243page.
244
245In order to enable [Prometheus](https://prometheus.io/) support, you need to use the
246configuration directive
247[`prometheus_retention_time`](/docs/agent/options.html#telemetry-prometheus_retention_time).
248
249Note: If your metric includes labels that use the same key name multiple times
250(i.e. tag=tag2 and tag=tag1), only the sorted last value (tag=tag2) will be visible on
251this endpoint due to a display issue. The complete label set is correctly applied and
252passed to external metrics providers even though it is not visible through this endpoint.
253
254| Method | Path                               | Produces                                   |
255| ------ | ---------------------------------- | ------------------------------------------ |
256| `GET`  | `/agent/metrics`                   | `application/json`                         |
257| `GET`  | `/agent/metrics?format=prometheus` | `text/plain; version=0.0.4; charset=utf-8` |
258
259The table below shows this endpoint's support for
260[blocking queries](/api/index.html#blocking-queries),
261[consistency modes](/api/index.html#consistency-modes),
262[agent caching](/api/index.html#agent-caching), and
263[required ACLs](/api/index.html#acls).
264
265| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
266| ---------------- | ----------------- | ------------- | ------------ |
267| `NO`             | `none`            | `none`        | `agent:read` |
268
269### Sample Request
270
271```text
272$ curl \
273    http://127.0.0.1:8500/v1/agent/metrics
274```
275
276### Sample Response
277
278```json
279{
280    "Timestamp": "2017-08-08 02:55:10 +0000 UTC",
281    "Gauges": [
282        {
283            "Name": "consul.consul.session_ttl.active",
284            "Value": 0,
285            "Labels": {}
286        },
287        {
288            "Name": "consul.runtime.alloc_bytes",
289            "Value": 4704344,
290            "Labels": {}
291        },
292        {
293            "Name": "consul.runtime.free_count",
294            "Value": 74063,
295            "Labels": {}
296        }
297    ],
298    "Points": [],
299    "Counters": [
300        {
301            "Name": "consul.consul.catalog.service.query",
302            "Count": 1,
303            "Sum": 1,
304            "Min": 1,
305            "Max": 1,
306            "Mean": 1,
307            "Stddev": 0,
308            "Labels": {
309                "service": "consul"
310            }
311        },
312        {
313            "Name": "consul.raft.apply",
314            "Count": 1,
315            "Sum": 1,
316            "Min": 1,
317            "Max": 1,
318            "Mean": 1,
319            "Stddev": 0,
320            "Labels": {}
321        }
322    ],
323    "Samples": [
324        {
325            "Name": "consul.consul.http.GET.v1.agent.metrics",
326            "Count": 1,
327            "Sum": 0.1817069947719574,
328            "Min": 0.1817069947719574,
329            "Max": 0.1817069947719574,
330            "Mean": 0.1817069947719574,
331            "Stddev": 0,
332            "Labels": {}
333        },
334        {
335            "Name": "consul.consul.http.GET.v1.catalog.service._",
336            "Count": 1,
337            "Sum": 0.23342099785804749,
338            "Min": 0.23342099785804749,
339            "Max": 0.23342099785804749,
340            "Mean": 0.23342099785804749,
341            "Stddev": 0,
342            "Labels": {}
343        },
344        {
345            "Name": "consul.serf.queue.Query",
346            "Count": 20,
347            "Sum": 0,
348            "Min": 0,
349            "Max": 0,
350            "Mean": 0,
351            "Stddev": 0,
352            "Labels": {}
353        }
354    ]
355}
356```
357
358- `Timestamp` is the timestamp of the interval for the displayed metrics. Metrics are
359aggregated on a ten second interval, so this value (along with the displayed metrics)
360will change every ten seconds.
361
362- `Gauges` is a list of gauges which store one value that is updated as time goes on,
363such as the amount of memory allocated.
364
365- `Points` is a list of point metrics, which each store a series of points under a given name.
366
367- `Counters` is a list of counters, which store info about a metric that is incremented
368over time such as the number of requests to an HTTP endpoint.
369
370- `Samples` is a list of samples, which store info about the amount of time spent on an
371operation, such as the time taken to serve a request to a specific http endpoint.
372
373## Stream Logs
374
375This endpoint streams logs from the local agent until the connection is closed.
376
377| Method | Path                         | Produces                   |
378| ------ | ---------------------------- | -------------------------- |
379| `GET`  | `/agent/monitor`             | `application/json`         |
380
381The table below shows this endpoint's support for
382[blocking queries](/api/index.html#blocking-queries),
383[consistency modes](/api/index.html#consistency-modes),
384[agent caching](/api/index.html#agent-caching), and
385[required ACLs](/api/index.html#acls).
386
387| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
388| ---------------- | ----------------- | ------------- | ------------ |
389| `NO`             | `none`            | `none`        | `agent:read` |
390
391### Parameters
392
393- `loglevel` `(string: "info")` - Specifies a text string containing a log level
394  to filter on, such as `info`.
395
396### Sample Request
397
398```text
399$ curl \
400    http://127.0.0.1:8500/v1/agent/monitor
401```
402
403### Sample Response
404
405```text
406YYYY/MM/DD HH:MM:SS [INFO] raft: Initial configuration (index=1): [{Suffrage:Voter ID:127.0.0.1:8300 Address:127.0.0.1:8300}]
407YYYY/MM/DD HH:MM:SS [INFO] raft: Node at 127.0.0.1:8300 [Follower] entering Follower state (Leader: "")
408YYYY/MM/DD HH:MM:SS [INFO] serf: EventMemberJoin: machine-osx 127.0.0.1
409YYYY/MM/DD HH:MM:SS [INFO] consul: Adding LAN server machine-osx (Addr: tcp/127.0.0.1:8300) (DC: dc1)
410YYYY/MM/DD HH:MM:SS [INFO] serf: EventMemberJoin: machine-osx.dc1 127.0.0.1
411YYYY/MM/DD HH:MM:SS [INFO] consul: Handled member-join event for server "machine-osx.dc1" in area "wan"
412# ...
413```
414
415## Join Agent
416
417This endpoint instructs the agent to attempt to connect to a given address.
418
419| Method | Path                         | Produces                   |
420| ------ | ---------------------------- | -------------------------- |
421| `PUT`  | `/agent/join/:address`       | `application/json`         |
422
423The table below shows this endpoint's support for
424[blocking queries](/api/index.html#blocking-queries),
425[consistency modes](/api/index.html#consistency-modes),
426[agent caching](/api/index.html#agent-caching), and
427[required ACLs](/api/index.html#acls).
428
429| Blocking Queries | Consistency Modes | Agent Caching | ACL Required  |
430| ---------------- | ----------------- | ------------- | ------------- |
431| `NO`             | `none`            | `none`        | `agent:write` |
432
433### Parameters
434
435- `address` `(string: <required>)` - Specifies the address of the other agent to
436  join. This is specified as part of the URL.
437
438- `wan` `(bool: false)` - Specifies to try and join over the WAN pool. This is
439  only optional for agents running in server mode. This is specified as part of
440  the URL as a query parameter
441
442### Sample Request
443
444```text
445$ curl \
446    http://127.0.0.1:8500/v1/agent/join/1.2.3.4
447```
448
449## Graceful Leave and Shutdown
450
451This endpoint triggers a graceful leave and shutdown of the agent. It is used to
452ensure other nodes see the agent as "left" instead of "failed". Nodes that leave
453will not attempt to re-join the cluster on restarting with a snapshot.
454
455For nodes in server mode, the node is removed from the Raft peer set in a
456graceful manner. This is critical, as in certain situations a non-graceful leave
457can affect cluster availability.
458
459| Method | Path                         | Produces                   |
460| ------ | ---------------------------- | -------------------------- |
461| `PUT`  | `/agent/leave`               | `application/json`         |
462
463The table below shows this endpoint's support for
464[blocking queries](/api/index.html#blocking-queries),
465[consistency modes](/api/index.html#consistency-modes),
466[agent caching](/api/index.html#agent-caching), and
467[required ACLs](/api/index.html#acls).
468
469| Blocking Queries | Consistency Modes | Agent Caching | ACL Required  |
470| ---------------- | ----------------- | ------------- | ------------- |
471| `NO`             | `none`            | `none`        | `agent:write` |
472
473### Sample Request
474
475```text
476$ curl \
477    --request PUT \
478    http://127.0.0.1:8500/v1/agent/leave
479```
480
481## Force Leave and Shutdown
482
483This endpoint instructs the agent to force a node into the `left` state. If a
484node fails unexpectedly, then it will be in a `failed` state. Once in the
485`failed` state, Consul will attempt to reconnect, and the services and checks
486belonging to that node will not be cleaned up. Forcing a node into the `left`
487state allows its old entries to be removed.
488
489| Method | Path                         | Produces                   |
490| ------ | ---------------------------- | -------------------------- |
491| `PUT`  | `/agent/force-leave/:node`   | `application/json`         |
492
493The table below shows this endpoint's support for
494[blocking queries](/api/index.html#blocking-queries),
495[consistency modes](/api/index.html#consistency-modes),
496[agent caching](/api/index.html#agent-caching), and
497[required ACLs](/api/index.html#acls).
498
499| Blocking Queries | Consistency Modes | Agent Caching | ACL Required  |
500| ---------------- | ----------------- | ------------- | ------------- |
501| `NO`             | `none`            | `none`        | `agent:write` |
502
503### Parameters
504
505- `node` `(string: <required>)` - Specifies the name of the node to be forced into `left` state. This is specified as part of the URL.
506
507### Sample Request
508
509```text
510$ curl \
511    --request PUT \
512    http://127.0.0.1:8500/v1/agent/force-leave/agent-one
513```
514
515## Update ACL Tokens
516
517This endpoint updates the ACL tokens currently in use by the agent. It can be
518used to introduce ACL tokens to the agent for the first time, or to update
519tokens that were initially loaded from the agent's configuration. Tokens are
520not persisted, so will need to be updated again if the agent is restarted.
521
522| Method | Path                                  | Produces                   |
523| ------ | ------------------------------------- | -------------------------- |
524| `PUT`  | `/agent/token/acl_token`              | `application/json`         |
525| `PUT`  | `/agent/token/acl_agent_token`        | `application/json`         |
526| `PUT`  | `/agent/token/acl_agent_master_token` | `application/json`         |
527| `PUT`  | `/agent/token/acl_replication_token`  | `application/json`         |
528
529The paths above correspond to the token names as found in the agent configuration:
530[`acl_token`](/docs/agent/options.html#acl_token), [`acl_agent_token`](/docs/agent/options.html#acl_agent_token),
531[`acl_agent_master_token`](/docs/agent/options.html#acl_agent_master_token), and
532[`acl_replication_token`](/docs/agent/options.html#acl_replication_token).
533
534The table below shows this endpoint's support for
535[blocking queries](/api/index.html#blocking-queries),
536[consistency modes](/api/index.html#consistency-modes),
537[agent caching](/api/index.html#agent-caching), and
538[required ACLs](/api/index.html#acls).
539
540| Blocking Queries | Consistency Modes | Agent Caching | ACL Required  |
541| ---------------- | ----------------- | ------------- | ------------- |
542| `NO`             | `none`            | `none`        | `agent:write` |
543
544### Parameters
545
546- `Token` `(string: "")` - Specifies the ACL token to set.
547
548### Sample Payload
549
550```json
551{
552  "Token": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
553}
554```
555
556### Sample Request
557
558```text
559$ curl \
560    --request PUT \
561    --data @payload.json \
562    http://127.0.0.1:8500/v1/agent/token/acl_token
563```
564