
# Endpoints

An actuator endpoint answers over HTTP when it is **enabled** and **exposed**. Enabled decides whether the endpoint exists at all; exposed decides whether HTTP shows it. Both are set with Spring Boot's `management.*` properties, and the endpoints answer on the web starter's server under `/actuator`.

## Why

The health check must be reachable by a load balancer, but the mappings of an application are nobody else's business. Exposing only `health` by default, as Spring Boot does, keeps the rest private until you choose otherwise.

## Example

```yaml
# lib/resources/application.yml
management:
  endpoints:
    web:
      base-path: /manage                 # /manage/health instead of /actuator/health
      exposure:
        include: "*"                     # every enabled endpoint...
        exclude: mappings                # ...but the mappings
      path-mapping:
        health: healthcheck              # /manage/healthcheck
      discovery:
        enabled: true
  endpoint:
    info:
      access: read-only
```

```properties
# lib/resources/application.properties: the same
management.endpoints.web.base-path=/manage
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=mappings
management.endpoints.web.path-mapping.health=healthcheck
management.endpoints.web.discovery.enabled=true
management.endpoint.info.access=read-only
```

```console
$ curl localhost:8080/manage/healthcheck
{"status":"UP"}
```

In YAML, quote `"*"`: a bare `*` is an alias.

## Enabled

An endpoint is enabled by the first of these that is set:

1. `management.endpoint.<id>.access`: `none` disables it, `read-only` and `unrestricted` enable it (Spring Boot 3.4 and later);
2. `management.endpoint.<id>.enabled`: `true` or `false` (Spring Boot 2 and 3);
3. `management.endpoints.access.default`: the access of every endpoint without its own;
4. `management.endpoints.enabled-by-default`;
5. the endpoint's own default: `@Endpoint(enableByDefault:)`, `true` for the built-in ones.

The built-in ids are `health`, `info`, `mappings`, `jsonschemas`, `isolates` and `qps`. The `qps` endpoint exists only when the web starter's debug feature is in the build (`spring.web.debug.qps.enabled: true`, see [Requests per second](qps.md)).

A disabled endpoint is neither exposed nor listed. An unknown `access` value stops the start (`must be one of none, read-only, unrestricted`). Only read operations exist so far, so `read-only` and `unrestricted` mean the same.

```properties
# Everything off, then health back on.
management.endpoints.enabled-by-default=false
management.endpoint.health.enabled=true
```

## Exposed

| Key | Default | Meaning |
|---|---|---|
| `management.endpoints.web.exposure.include` | `health` | The ids exposed over HTTP, or `*` for all |
| `management.endpoints.web.exposure.exclude` | none | The ids not exposed, or `*`; wins over `include` |

## Paths

| Key | Default | Meaning |
|---|---|---|
| `management.endpoints.web.base-path` | `/actuator` | The path under which the endpoints are. `/` puts them at the root (`/health`), without the discovery page. A missing leading `/` is added, trailing ones dropped |
| `management.endpoints.web.path-mapping.<id>` | the id | Another path for one endpoint |
| `management.endpoints.web.discovery.enabled` | `true` | Whether the base path answers the links to the exposed endpoints |

The endpoints are under `server.context-path` like every other path of the web starter. There is no separate management port.

## The discovery page

`GET /actuator` lists the exposed endpoints:

```json
{"_links": {
  "self": {"href": "http://localhost:8080/actuator", "templated": false},
  "health": {"href": "http://localhost:8080/actuator/health", "templated": false},
  "health-path": {"href": "http://localhost:8080/actuator/health/{*path}", "templated": true},
  "info": {"href": "http://localhost:8080/actuator/info", "templated": false}}}
```

## Media types and status codes

| Request | Answer |
|---|---|
| `Accept: application/vnd.spring-boot.actuator.v3+json`, `*/*` or none | Version 3 JSON, `application/vnd.spring-boot.actuator.v3+json` |
| `Accept: application/json` | The same JSON as `application/json` |
| `Accept: application/vnd.spring-boot.actuator.v2+json` | Version 2 JSON (the health's parts under `details`) |
| an `Accept` the endpoint cannot give | `406` |
| a method other than `GET` and `HEAD` | `405` |
| an operation that answers `null` | `404` |
| a query parameter that is missing or cannot be converted | `400` |

## In Spring (Java)

The same keys, defaults and media types. Spring Boot can also expose endpoints over JMX and on a separate `management.server.port`; here they are HTTP on the main server only.

## See also

- [Health](health.md)
- [Mappings](mappings.md)
- [JSON Schemas](json-schemas.md)
- [Isolates](isolates.md)
- [Requests per second](qps.md)
- [Endpoints of your own](custom-endpoints.md)
- [Security](security.md)
- [All properties](properties.md)
