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