1--- 2layout: api 3page_title: Agent - HTTP API 4description: |- 5 The /agent endpoints interact with the local Consul agent to register 6 services, checks, list members, and more. 7--- 8 9# Agent HTTP API 10 11The `/agent` endpoints are used to interact with the local Consul agent. 12Usually, services and checks are registered with an agent which then takes on 13the burden of keeping that data synchronized with the cluster. For example, the 14agent registers services and checks with the Catalog and performs 15[anti-entropy](/docs/internals/anti-entropy) to recover from outages. 16 17In addition to these endpoints, additional endpoints are grouped in the 18navigation for `Checks` and `Services`. 19 20## Retrieve host information 21 22This endpoint returns information about the host the agent is running on such as 23CPU, memory, and disk. 24 25~> Note: this is not a stable API. The structure of the response body may change 26at any time. If you require this data to be in a stable format, please open a 27GitHub issue to discuss your use case. 28 29| Method | Path | Produces | 30| ------ | ---------------- | ------------------ | 31| `GET` | `/agent/host` | `application/json` | 32 33The table below shows this endpoint's support for 34[blocking queries](/api/features/blocking), 35[consistency modes](/api/features/consistency), 36[agent caching](/api/features/caching), and 37[required ACLs](/api#authentication). 38 39| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 40| ---------------- | ----------------- | ------------- | --------------- | 41| `NO` | `none` | `none` | `operator:read` | 42 43### Sample Request 44 45```shell-session 46$ curl \ 47 http://127.0.0.1:8500/v1/agent/host 48``` 49 50### Sample Response 51 52```json 53{ 54 "Memory": { 55 "total": 8192864256, 56 "available": 7154810880, 57 "used": 1406787584, 58 "usedPercent": 17.17088847126628, 59 "free": 1683918848, 60 "active": 2873405440, 61 "inactive": 2777124864, 62 "wired": 0, 63 "laundry": 0, 64 "buffers": 131567616, 65 "cached": 4970590208, 66 "writeBack": 0, 67 "dirty": 1069056, 68 "writeBackTmp": 0, 69 "shared": 9121792, 70 "slab": 770506752, 71 "sreclaimable": 0, 72 "sunreclaim": 0, 73 "pageTables": 5103616, 74 "swapCached": 143360, 75 "commitLimit": 4201283584, 76 "committedAS": 1514496000, 77 "highTotal": 0, 78 "highFree": 0, 79 "lowTotal": 0, 80 "lowFree": 0, 81 "swapTotal": 104853504, 82 "swapFree": 99696640, 83 "mapped": 313540608, 84 "vmallocTotal": 269240696832, 85 "vmallocUsed": 25956352, 86 "vmallocChunk": 0, 87 "hugePagesTotal": 0, 88 "hugePagesFree": 0, 89 "hugePageSize": 0 90 }, 91 "CPU": [ 92 { 93 "cpu": 0, 94 "vendorId": "", 95 "family": "", 96 "model": "", 97 "stepping": 0, 98 "physicalId": "", 99 "coreId": "0", 100 "cores": 1, 101 "modelName": "", 102 "mhz": 1500, 103 "cacheSize": 0, 104 "flags": [ 105 "fp", 106 "asimd", 107 "evtstrm", 108 "crc32", 109 "cpuid" 110 ], 111 "microcode": "" 112 }, 113 { 114 "cpu": 1, 115 "vendorId": "", 116 "family": "", 117 "model": "", 118 "stepping": 0, 119 "physicalId": "", 120 "coreId": "1", 121 "cores": 1, 122 "modelName": "", 123 "mhz": 1500, 124 "cacheSize": 0, 125 "flags": [ 126 "fp", 127 "asimd", 128 "evtstrm", 129 "crc32", 130 "cpuid" 131 ], 132 "microcode": "" 133 }, 134 { 135 "cpu": 2, 136 "vendorId": "", 137 "family": "", 138 "model": "", 139 "stepping": 0, 140 "physicalId": "", 141 "coreId": "2", 142 "cores": 1, 143 "modelName": "", 144 "mhz": 1500, 145 "cacheSize": 0, 146 "flags": [ 147 "fp", 148 "asimd", 149 "evtstrm", 150 "crc32", 151 "cpuid" 152 ], 153 "microcode": "" 154 }, 155 { 156 "cpu": 3, 157 "vendorId": "", 158 "family": "", 159 "model": "", 160 "stepping": 0, 161 "physicalId": "", 162 "coreId": "3", 163 "cores": 1, 164 "modelName": "", 165 "mhz": 1500, 166 "cacheSize": 0, 167 "flags": [ 168 "fp", 169 "asimd", 170 "evtstrm", 171 "crc32", 172 "cpuid" 173 ], 174 "microcode": "" 175 } 176 ], 177 "Host": { 178 "hostname": "hashicorp-consul-server-2", 179 "uptime": 6855759, 180 "bootTime": 1620226737, 181 "procs": 1, 182 "os": "linux", 183 "platform": "alpine", 184 "platformFamily": "alpine", 185 "platformVersion": "3.13.5", 186 "kernelVersion": "5.10.17-v8+", 187 "kernelArch": "aarch64", 188 "virtualizationSystem": "", 189 "virtualizationRole": "", 190 "hostId": "7a8ef887-9dbe-4ed3-b45b-c04d7ee6476f" 191 }, 192 "Disk": { 193 "path": "/", 194 "fstype": "", 195 "total": 125550247936, 196 "free": 93488398336, 197 "used": 26909102080, 198 "usedPercent": 22.350216563486036, 199 "inodesTotal": 7684080, 200 "inodesUsed": 442088, 201 "inodesFree": 7241992, 202 "inodesUsedPercent": 5.753297727249065 203 }, 204 "CollectionTime": 1627082496166088783, 205 "Errors": null 206} 207``` 208 209## List Members 210 211This endpoint returns the members the agent sees in the cluster gossip pool. Due 212to the nature of gossip, this is eventually consistent: the results may differ 213by agent. The strongly consistent view of nodes is instead provided by 214`/v1/catalog/nodes`. 215 216| Method | Path | Produces | 217| ------ | ---------------- | ------------------ | 218| `GET` | `/agent/members` | `application/json` | 219 220The table below shows this endpoint's support for 221[blocking queries](/api/features/blocking), 222[consistency modes](/api/features/consistency), 223[agent caching](/api/features/caching), and 224[required ACLs](/api#authentication). 225 226| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 227| ---------------- | ----------------- | ------------- | ------------ | 228| `NO` | `none` | `none` | `node:read` | 229 230### Parameters 231 232- `wan` `(bool: false)` - Specifies to list WAN members instead of the LAN 233 members (which is the default). This is only eligible for agents running in 234 **server mode**. This is specified as part of the URL as a query parameter. 235 236- `segment` `(string: "")` <EnterpriseAlert inline /> - Specifies the segment to list members for. 237 If left blank, this will query for the default segment when connecting to a server and 238 the agent's own segment when connecting to a client (clients can only be part of one 239 network segment). When querying a server, setting this to the special string `_all` 240 will show members in all segments. 241 242### Sample Request 243 244```shell-session 245$ curl \ 246 http://127.0.0.1:8500/v1/agent/members 247``` 248 249### Sample Response 250 251```json 252[ 253 { 254 "Name": "foobar", 255 "Addr": "10.1.10.12", 256 "Port": 8301, 257 "Tags": { 258 "bootstrap": "1", 259 "dc": "dc1", 260 "port": "8300", 261 "role": "consul" 262 }, 263 "Status": 1, 264 "ProtocolMin": 1, 265 "ProtocolMax": 2, 266 "ProtocolCur": 2, 267 "DelegateMin": 1, 268 "DelegateMax": 3, 269 "DelegateCur": 3 270 } 271] 272``` 273 274## Read Configuration 275 276This endpoint returns the configuration and member information of the local 277agent. The `Config` element contains a subset of the configuration and its 278format will not change in a backwards incompatible way between releases. 279`DebugConfig` contains the full runtime configuration but its format is subject 280to change without notice or deprecation. 281 282| Method | Path | Produces | 283| ------ | ------------- | ------------------ | 284| `GET` | `/agent/self` | `application/json` | 285 286The table below shows this endpoint's support for 287[blocking queries](/api/features/blocking), 288[consistency modes](/api/features/consistency), 289[agent caching](/api/features/caching), and 290[required ACLs](/api#authentication). 291 292| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 293| ---------------- | ----------------- | ------------- | ------------ | 294| `NO` | `none` | `none` | `agent:read` | 295 296### Sample Request 297 298```shell-session 299$ curl \ 300 http://127.0.0.1:8500/v1/agent/self 301``` 302 303### Sample Response 304 305```json 306{ 307 "Config": { 308 "Datacenter": "dc1", 309 "NodeName": "foobar", 310 "NodeID": "9d754d17-d864-b1d3-e758-f3fe25a9874f", 311 "Server": true, 312 "Revision": "deadbeef", 313 "Version": "1.0.0" 314 }, 315 "DebugConfig": { 316 ... full runtime configuration ... 317 ... format subject to change ... 318 }, 319 "Coord": { 320 "Adjustment": 0, 321 "Error": 1.5, 322 "Vec": [0,0,0,0,0,0,0,0] 323 }, 324 "Member": { 325 "Name": "foobar", 326 "Addr": "10.1.10.12", 327 "Port": 8301, 328 "Tags": { 329 "bootstrap": "1", 330 "dc": "dc1", 331 "id": "40e4a748-2192-161a-0510-9bf59fe950b5", 332 "port": "8300", 333 "role": "consul", 334 "vsn": "1", 335 "vsn_max": "1", 336 "vsn_min": "1" 337 }, 338 "Status": 1, 339 "ProtocolMin": 1, 340 "ProtocolMax": 2, 341 "ProtocolCur": 2, 342 "DelegateMin": 2, 343 "DelegateMax": 4, 344 "DelegateCur": 4 345 }, 346 "Meta": { 347 "instance_type": "i2.xlarge", 348 "os_version": "ubuntu_16.04" 349 } 350} 351``` 352 353## Reload Agent 354 355This endpoint instructs the agent to reload its configuration. Any errors 356encountered during this process are returned. 357 358Not all configuration options are reloadable. See the 359[Reloadable Configuration](/docs/agent/options#reloadable-configuration) 360section on the agent options page for details on which options are supported. 361 362| Method | Path | Produces | 363| ------ | --------------- | ------------------ | 364| `PUT` | `/agent/reload` | `application/json` | 365 366The table below shows this endpoint's support for 367[blocking queries](/api/features/blocking), 368[consistency modes](/api/features/consistency), 369[agent caching](/api/features/caching), and 370[required ACLs](/api#authentication). 371 372| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 373| ---------------- | ----------------- | ------------- | ------------- | 374| `NO` | `none` | `none` | `agent:write` | 375 376### Sample Request 377 378```shell-session 379$ curl \ 380 --request PUT \ 381 http://127.0.0.1:8500/v1/agent/reload 382``` 383 384## Enable Maintenance Mode 385 386This endpoint places the agent into "maintenance mode". During maintenance mode, 387the node will be marked as unavailable and will not be present in DNS or API 388queries. This API call is idempotent. 389 390Maintenance mode is persistent and will be automatically restored on agent 391restart. 392 393| Method | Path | Produces | 394| ------ | -------------------- | ------------------ | 395| `PUT` | `/agent/maintenance` | `application/json` | 396 397The table below shows this endpoint's support for 398[blocking queries](/api/features/blocking), 399[consistency modes](/api/features/consistency), 400[agent caching](/api/features/caching), and 401[required ACLs](/api#authentication). 402 403| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 404| ---------------- | ----------------- | ------------- | ------------ | 405| `NO` | `none` | `none` | `node:write` | 406 407### Parameters 408 409- `enable` `(bool: <required>)` - Specifies whether to enable or disable 410 maintenance mode. This is specified as part of the URL as a query string 411 parameter. 412 413- `reason` `(string: "")` - Specifies a text string explaining the reason for 414 placing the node into maintenance mode. This is simply to aid human operators. 415 If no reason is provided, a default value will be used instead. This is 416 specified as part of the URL as a query string parameter, and, as such, must 417 be URI-encoded. 418 419### Sample Request 420 421```shell-session 422$ curl \ 423 --request PUT \ 424 http://127.0.0.1:8500/v1/agent/maintenance?enable=true&reason=For+API+docs 425``` 426 427## View Metrics 428 429This endpoint will dump the metrics for the most recent finished interval. 430For more information about metrics, see the [telemetry](/docs/agent/telemetry) 431page. 432 433In order to enable [Prometheus](https://prometheus.io/) support, you need to use the 434configuration directive 435[`prometheus_retention_time`](/docs/agent/options#telemetry-prometheus_retention_time). 436 437Since Consul 1.7.2 this endpoint will also automatically switch output format if 438the request contains an `Accept` header with a compatible MIME type such as 439`application/openmetrics-text`. Prometheus v2.5.0 and newer pass this header in scraping 440queries, and so will get a compatible format by default. Older versions of Prometheus may 441work by default as several previously used MIME types are also detected, but the `?format` 442query parameter may also be used to specify the output format manually if needed. 443simplifying scrape configuration. 444 445Note: If using the default format and your metric includes labels that use the same key 446name multiple times (i.e. tag=tag2 and tag=tag1), only the sorted last value (tag=tag2) 447will be visible on this endpoint due to a display issue. The complete label set is correctly 448applied and passed to external metrics providers even though it is not visible through this 449endpoint. 450 451| Method | Path | Produces | 452| ------ | ---------------------------------- | ------------------------------------------ | 453| `GET` | `/agent/metrics` | `application/json` | 454| `GET` | `/agent/metrics?format=prometheus` | `text/plain; version=0.0.4; charset=utf-8` | 455 456The table below shows this endpoint's support for 457[blocking queries](/api/features/blocking), 458[consistency modes](/api/features/consistency), 459[agent caching](/api/features/caching), and 460[required ACLs](/api#authentication). 461 462| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 463| ---------------- | ----------------- | ------------- | ------------ | 464| `NO` | `none` | `none` | `agent:read` | 465 466### Sample Request 467 468```shell-session 469$ curl \ 470 http://127.0.0.1:8500/v1/agent/metrics 471``` 472 473### Sample Response 474 475```json 476{ 477 "Timestamp": "2017-08-08 02:55:10 +0000 UTC", 478 "Gauges": [ 479 { 480 "Name": "consul.consul.session_ttl.active", 481 "Value": 0, 482 "Labels": {} 483 }, 484 { 485 "Name": "consul.runtime.alloc_bytes", 486 "Value": 4704344, 487 "Labels": {} 488 }, 489 { 490 "Name": "consul.runtime.free_count", 491 "Value": 74063, 492 "Labels": {} 493 } 494 ], 495 "Points": [], 496 "Counters": [ 497 { 498 "Name": "consul.consul.catalog.service.query", 499 "Count": 1, 500 "Sum": 1, 501 "Min": 1, 502 "Max": 1, 503 "Mean": 1, 504 "Stddev": 0, 505 "Labels": { 506 "service": "consul" 507 } 508 }, 509 { 510 "Name": "consul.raft.apply", 511 "Count": 1, 512 "Sum": 1, 513 "Min": 1, 514 "Max": 1, 515 "Mean": 1, 516 "Stddev": 0, 517 "Labels": {} 518 } 519 ], 520 "Samples": [ 521 { 522 "Name": "consul.consul.http.GET.v1.agent.metrics", 523 "Count": 1, 524 "Sum": 0.1817069947719574, 525 "Min": 0.1817069947719574, 526 "Max": 0.1817069947719574, 527 "Mean": 0.1817069947719574, 528 "Stddev": 0, 529 "Labels": {} 530 }, 531 { 532 "Name": "consul.consul.http.GET.v1.catalog.service._", 533 "Count": 1, 534 "Sum": 0.23342099785804749, 535 "Min": 0.23342099785804749, 536 "Max": 0.23342099785804749, 537 "Mean": 0.23342099785804749, 538 "Stddev": 0, 539 "Labels": {} 540 }, 541 { 542 "Name": "consul.serf.queue.Query", 543 "Count": 20, 544 "Sum": 0, 545 "Min": 0, 546 "Max": 0, 547 "Mean": 0, 548 "Stddev": 0, 549 "Labels": {} 550 } 551 ] 552} 553``` 554 555- `Timestamp` is the timestamp of the interval for the displayed metrics. Metrics are 556 aggregated on a ten second interval, so this value (along with the displayed metrics) 557 will change every ten seconds. 558 559- `Gauges` is a list of gauges which store one value that is updated as time goes on, 560 such as the amount of memory allocated. 561 562- `Points` is a list of point metrics, which each store a series of points under a given name. 563 564- `Counters` is a list of counters, which store info about a metric that is incremented 565 over time such as the number of requests to an HTTP endpoint. 566 567- `Samples` is a list of samples, which store info about the amount of time spent on an 568 operation, such as the time taken to serve a request to a specific http endpoint. 569 570## Stream Logs 571 572This endpoint streams logs from the local agent until the connection is closed. 573 574| Method | Path | Produces | 575| ------ | ---------------- | ------------------ | 576| `GET` | `/agent/monitor` | `application/json` | 577 578The table below shows this endpoint's support for 579[blocking queries](/api/features/blocking), 580[consistency modes](/api/features/consistency), 581[agent caching](/api/features/caching), and 582[required ACLs](/api#authentication). 583 584| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 585| ---------------- | ----------------- | ------------- | ------------ | 586| `NO` | `none` | `none` | `agent:read` | 587 588### Parameters 589 590- `loglevel` `(string: "info")` - Specifies a text string containing a log level 591 to filter on, such as `info`. 592- `logjson` `(bool: false)` - Specifies whether the logs will be output in JSON 593 format. 594 595### Sample Request 596 597```shell-session 598$ curl \ 599 http://127.0.0.1:8500/v1/agent/monitor 600``` 601 602### Sample Response 603 604```log 605YYYY/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}] 606YYYY/MM/DD HH:MM:SS [INFO] raft: Node at 127.0.0.1:8300 [Follower] entering Follower state (Leader: "") 607YYYY/MM/DD HH:MM:SS [INFO] serf: EventMemberJoin: machine-osx 127.0.0.1 608YYYY/MM/DD HH:MM:SS [INFO] consul: Adding LAN server machine-osx (Addr: tcp/127.0.0.1:8300) (DC: dc1) 609YYYY/MM/DD HH:MM:SS [INFO] serf: EventMemberJoin: machine-osx.dc1 127.0.0.1 610YYYY/MM/DD HH:MM:SS [INFO] consul: Handled member-join event for server "machine-osx.dc1" in area "wan" 611# ... 612``` 613 614## Join Agent 615 616This endpoint instructs the agent to attempt to connect to a given address. 617 618| Method | Path | Produces | 619| ------ | ---------------------- | ------------------ | 620| `PUT` | `/agent/join/:address` | `application/json` | 621 622The table below shows this endpoint's support for 623[blocking queries](/api/features/blocking), 624[consistency modes](/api/features/consistency), 625[agent caching](/api/features/caching), and 626[required ACLs](/api#authentication). 627 628| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 629| ---------------- | ----------------- | ------------- | ------------- | 630| `NO` | `none` | `none` | `agent:write` | 631 632### Parameters 633 634- `address` `(string: <required>)` - Specifies the address of the other agent to 635 join. This is specified as part of the URL. 636 637- `wan` `(bool: false)` - Specifies to try and join over the WAN pool. This is 638 only optional for agents running in server mode. This is specified as part of 639 the URL as a query parameter 640 641### Sample Request 642 643```shell-session 644$ curl \ 645 http://127.0.0.1:8500/v1/agent/join/1.2.3.4 646``` 647 648## Graceful Leave and Shutdown 649 650This endpoint triggers a graceful leave and shutdown of the agent. It is used to 651ensure other nodes see the agent as "left" instead of "failed". Nodes that leave 652will not attempt to re-join the cluster on restarting with a snapshot. 653 654For nodes in server mode, the node is removed from the Raft peer set in a 655graceful manner. This is critical, as in certain situations a non-graceful leave 656can affect cluster availability. 657 658| Method | Path | Produces | 659| ------ | -------------- | ------------------ | 660| `PUT` | `/agent/leave` | `application/json` | 661 662The table below shows this endpoint's support for 663[blocking queries](/api/features/blocking), 664[consistency modes](/api/features/consistency), 665[agent caching](/api/features/caching), and 666[required ACLs](/api#authentication). 667 668| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 669| ---------------- | ----------------- | ------------- | ------------- | 670| `NO` | `none` | `none` | `agent:write` | 671 672### Sample Request 673 674```shell-session 675$ curl \ 676 --request PUT \ 677 http://127.0.0.1:8500/v1/agent/leave 678``` 679 680## Force Leave and Shutdown 681 682This endpoint instructs the agent to force a node into the `left` state. If a 683node fails unexpectedly, then it will be in a `failed` state. Once in the 684`failed` state, Consul will attempt to reconnect, and the services and checks 685belonging to that node will not be cleaned up. Forcing a node into the `left` 686state allows its old entries to be removed. 687 688| Method | Path | Produces | 689| ------ | -------------------------- | ------------------ | 690| `PUT` | `/agent/force-leave/:node` | `application/json` | 691 692Additionally, by specifying the `prune` flag, a node can be forcibly removed from 693the list of members entirely. 694 695| Method | Path | Produces | 696| ------ | -------------------------------- | ------------------ | 697| `PUT` | `/agent/force-leave/:node?prune` | `application/json` | 698 699The table below shows this endpoint's support for 700[blocking queries](/api/features/blocking), 701[consistency modes](/api/features/consistency), 702[agent caching](/api/features/caching), and 703[required ACLs](/api#authentication). 704 705| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 706| ---------------- | ----------------- | ------------- | ---------------- | 707| `NO` | `none` | `none` | `operator:write` | 708 709### Parameters 710 711- `node` `(string: <required>)` - Specifies the name of the node to be forced into `left` state. This is specified as part of the URL. 712 713### Sample Request 714 715```shell-session 716$ curl \ 717 --request PUT \ 718 http://127.0.0.1:8500/v1/agent/force-leave/agent-one 719``` 720 721## Update ACL Tokens 722 723This endpoint updates the ACL tokens currently in use by the agent. It can be 724used to introduce ACL tokens to the agent for the first time, or to update 725tokens that were initially loaded from the agent's configuration. Tokens will be persisted 726only if the [`acl.enable_token_persistence`](/docs/agent/options#acl_enable_token_persistence) 727configuration is `true`. When not being persisted, they will need to be reset if the agent 728is restarted. 729 730| Method | Path | Produces | 731| ------ | --------------------------- | ------------------ | 732| `PUT` | `/agent/token/default` | `application/json` | 733| `PUT` | `/agent/token/agent` | `application/json` | 734| `PUT` | `/agent/token/agent_master` | `application/json` | 735| `PUT` | `/agent/token/replication` | `application/json` | 736 737The paths above correspond to the token names as found in the agent configuration: 738[`default`](/docs/agent/options#acl_tokens_default), [`agent`](/docs/agent/options#acl_tokens_agent), 739[`agent_master`](/docs/agent/options#acl_tokens_agent_master), and 740[`replication`](/docs/agent/options#acl_tokens_replication). 741 742-> **Deprecation Note:** The following paths were deprecated in version 1.4.3 743 744| Method | Path | Produces | 745| ------ | ------------------------------------- | ------------------ | 746| `PUT` | `/agent/token/acl_token` | `application/json` | 747| `PUT` | `/agent/token/acl_agent_token` | `application/json` | 748| `PUT` | `/agent/token/acl_agent_master_token` | `application/json` | 749| `PUT` | `/agent/token/acl_replication_token` | `application/json` | 750 751The paths above correspond to the token names as found in the agent configuration: 752[`acl_token`](/docs/agent/options#acl_token_legacy), [`acl_agent_token`](/docs/agent/options#acl_agent_token_legacy), 753[`acl_agent_master_token`](/docs/agent/options#acl_agent_master_token_legacy), and 754[`acl_replication_token`](/docs/agent/options#acl_replication_token_legacy). 755 756The table below shows this endpoint's support for 757[blocking queries](/api/features/blocking), 758[consistency modes](/api/features/consistency), 759[agent caching](/api/features/caching), and 760[required ACLs](/api#authentication). 761 762| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 763| ---------------- | ----------------- | ------------- | ------------- | 764| `NO` | `none` | `none` | `agent:write` | 765 766### Parameters 767 768- `Token` `(string: "")` - Specifies the ACL token to set. 769 770### Sample Payload 771 772```json 773{ 774 "Token": "adf4238a-882b-9ddc-4a9d-5b6758e4159e" 775} 776``` 777 778### Sample Request 779 780```shell-session 781$ curl \ 782 --request PUT \ 783 --data @payload.json \ 784 http://127.0.0.1:8500/v1/agent/token/acl_token 785``` 786