1--- 2layout: api 3page_title: Service - Agent - HTTP API 4sidebar_current: api-agent-service 5description: |- 6 The /agent/service endpoints interact with services on the local agent in 7 Consul. 8--- 9 10# Service - Agent HTTP API 11 12The `/agent/service` endpoints interact with checks on the local agent in 13Consul. These should not be confused with services in the catalog. 14 15## List Services 16 17This endpoint returns all the services that are registered with 18the local agent. These services were either provided through configuration files 19or added dynamically using the HTTP API. 20 21It is important to note that the services known by the agent may be different 22from those reported by the catalog. This is usually due to changes being made 23while there is no leader elected. The agent performs active 24[anti-entropy](/docs/internals/anti-entropy.html), so in most situations 25everything will be in sync within a few seconds. 26 27| Method | Path | Produces | 28| ------ | ---------------------------- | -------------------------- | 29| `GET` | `/agent/services` | `application/json` | 30 31The table below shows this endpoint's support for 32[blocking queries](/api/index.html#blocking-queries), 33[consistency modes](/api/index.html#consistency-modes), and 34[required ACLs](/api/index.html#acls). 35 36| Blocking Queries | Consistency Modes | ACL Required | 37| ---------------- | ----------------- | -------------- | 38| `NO` | `none` | `service:read` | 39 40### Sample Request 41 42```text 43$ curl \ 44 https://consul.rocks/v1/agent/services 45``` 46 47### Sample Response 48 49```json 50{ 51 "redis": { 52 "ID": "redis", 53 "Service": "redis", 54 "Tags": null, 55 "Address": "", 56 "Port": 8000 57 } 58} 59``` 60 61## Register Service 62 63This endpoint adds a new service, with an optional health check, to the local 64agent. 65 66The agent is responsible for managing the status of its local services, and for 67sending updates about its local services to the servers to keep the global 68catalog in sync. 69 70| Method | Path | Produces | 71| ------ | ---------------------------- | -------------------------- | 72| `PUT` | `/agent/service/register` | `application/json` | 73 74The table below shows this endpoint's support for 75[blocking queries](/api/index.html#blocking-queries), 76[consistency modes](/api/index.html#consistency-modes), and 77[required ACLs](/api/index.html#acls). 78 79| Blocking Queries | Consistency Modes | ACL Required | 80| ---------------- | ----------------- | --------------- | 81| `NO` | `none` | `service:write` | 82 83### Parameters 84 85- `Name` `(string: <required>)` - Specifies the logical name of the service. 86 Many service instances may share the same logical service name. 87 88- `ID` `(string: "")` - Specifies a unique ID for this service. This must be 89 unique per _agent_. This defaults to the `Name` parameter if not provided. 90 91- `Tags` `(array<string>: nil)` - Specifies a list of tags to assign to the 92 service. These tags can be used for later filtering and are exposed via the 93 APIs. 94 95- `Address` `(string: "")` - Specifies the address of the service. If not 96 provided, the agent's address is used as the address for the service during 97 DNS queries. 98 99- `Check` `(Check: nil)` - Specifies a check. Please see the 100 [check documentation](/api/agent/check.html) for more information about the 101 accepted fields. If you don't provide a name or id for the check then they 102 will be generated. To provide a custom id and/or name set the `CheckID` 103 and/or `Name` field. 104 105- `Checks` `(array<Check>: nil`) - Specifies a list of checks. Please see the 106 [check documentation](/api/agent/check.html) for more information about the 107 accepted fields. If you don't provide a name or id for the check then they 108 will be generated. To provide a custom id and/or name set the `CheckID` 109 and/or `Name` field. The automatically generated `Name` and `CheckID` depend 110 on the position of the check within the array, so even though the behavior is 111 deterministic, it is recommended for all checks to either let consul set the 112 `CheckID` by leaving the field empty/omitting it or to provide a unique value. 113 114- `EnableTagOverride` `(bool: false)` - Specifies to disable the anti-entropy 115 feature for this service's tags. If `EnableTagOverride` is set to `true` then 116 external agents can update this service in the [catalog](/api/catalog.html) 117 and modify the tags. Subsequent local sync operations by this agent will 118 ignore the updated tags. For instance, if an external agent modified both the 119 tags and the port for this service and `EnableTagOverride` was set to `true` 120 then after the next sync cycle the service's port would revert to the original 121 value but the tags would maintain the updated value. As a counter example, if 122 an external agent modified both the tags and port for this service and 123 `EnableTagOverride` was set to `false` then after the next sync cycle the 124 service's port _and_ the tags would revert to the original value and all 125 modifications would be lost. 126 127 It is important to note that this applies only to the locally registered 128 service. If you have multiple nodes all registering the same service their 129 `EnableTagOverride` configuration and all other service configuration items 130 are independent of one another. Updating the tags for the service registered 131 on one node is independent of the same service (by name) registered on 132 another node. If `EnableTagOverride` is not specified the default value is 133 `false`. See [anti-entropy syncs](/docs/internals/anti-entropy.html) for 134 more info. 135 136### Sample Payload 137 138```json 139{ 140 "ID": "redis1", 141 "Name": "redis", 142 "Tags": [ 143 "primary", 144 "v1" 145 ], 146 "Address": "127.0.0.1", 147 "Port": 8000, 148 "EnableTagOverride": false, 149 "Check": { 150 "DeregisterCriticalServiceAfter": "90m", 151 "Args": ["/usr/local/bin/check_redis.py"], 152 "HTTP": "http://localhost:5000/health", 153 "Interval": "10s", 154 "TTL": "15s" 155 } 156} 157``` 158 159### Sample Request 160 161```text 162$ curl \ 163 --request PUT \ 164 --data @payload.json \ 165 https://consul.rocks/v1/agent/service/register 166``` 167 168## Deregister Service 169 170This endpoint removes a service from the local agent. If the service does not 171exist, no action is taken. 172 173The agent will take care of deregistering the service with the catalog. If there 174is an associated check, that is also deregistered. 175 176| Method | Path | Produces | 177| ------ | ---------------------------- | -------------------------- | 178| `PUT` | `/agent/service/deregister/:service_id` | `application/json` | 179 180The table below shows this endpoint's support for 181[blocking queries](/api/index.html#blocking-queries), 182[consistency modes](/api/index.html#consistency-modes), and 183[required ACLs](/api/index.html#acls). 184 185| Blocking Queries | Consistency Modes | ACL Required | 186| ---------------- | ----------------- | --------------- | 187| `NO` | `none` | `service:write` | 188 189### Parameters 190 191- `service_id` `(string: <required>)` - Specifies the ID of the service to 192 deregister. This is specified as part of the URL. 193 194### Sample Request 195 196```text 197$ curl \ 198 --request PUT \ 199 https://consul.rocks/v1/agent/service/deregister/my-service-id 200``` 201 202## Enable Maintenance Mode 203 204This endpoint places a given service into "maintenance mode". During maintenance 205mode, the service will be marked as unavailable and will not be present in DNS 206or API queries. This API call is idempotent. Maintenance mode is persistent and 207will be automatically restored on agent restart. 208 209| Method | Path | Produces | 210| ------ | ---------------------------- | -------------------------- | 211| `PUT` | `/agent/service/maintenance/:service_id` | `application/json` | 212 213The table below shows this endpoint's support for 214[blocking queries](/api/index.html#blocking-queries), 215[consistency modes](/api/index.html#consistency-modes), and 216[required ACLs](/api/index.html#acls). 217 218| Blocking Queries | Consistency Modes | ACL Required | 219| ---------------- | ----------------- | --------------- | 220| `NO` | `none` | `service:write` | 221 222### Parameters 223 224- `service_id` `(string: <required>)` - Specifies the ID of the service to put 225 in maintenance mode. This is specified as part of the URL. 226 227- `enable` `(bool: <required>)` - Specifies whether to enable or disable 228 maintenance mode. This is specified as part of the URL as a query string 229 parameter. 230 231- `reason` `(string: "")` - Specifies a text string explaining the reason for 232 placing the node into maintenance mode. This is simply to aid human operators. 233 If no reason is provided, a default value will be used instead. This is 234 specified as part of the URL as a query string parameter, and, as such, must 235 be URI-encoded. 236 237### Sample Request 238 239```text 240$ curl \ 241 --request PUT \ 242 https://consul.rocks/v1/agent/service/maintenance/my-service-id?enable=true&reason=For+the+docs 243``` 244