consul/website/content/api-docs/config.mdx

---
layout: api
page_title: Config - HTTP API
description: |-
  The /config endpoints are for managing centralized configuration
  in Consul.
---

# Config HTTP Endpoint

The `/config` endpoints create, update, delete and query central configuration
entries registered with Consul. See the
[agent configuration](/docs/agent/config/config-files#enable_central_service_config)
for more information on how to enable this functionality for centrally
configuring services and [configuration entries docs](/docs/agent/config-entries) for a description
of the configuration entries content.

## Apply Configuration

This endpoint creates or updates the given config entry.

| Method | Path      | Produces           |
| ------ | --------- | ------------------ |
| `PUT`  | `/config` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                                      |
| ---------------- | ----------------- | ------------- | ------------------------------------------------- |
| `NO`             | `none`            | `none`        | `service:write`<br />`operator:write`<sup>1</sup> |

<p>
  <sup>1</sup> The ACL required depends on the config entry kind being updated:
</p>

| Config Entry Kind   | Required ACL       |
| ------------------- | ------------------ |
| ingress-gateway     | `operator:write`   |
| proxy-defaults      | `operator:write`   |
| service-defaults    | `service:write`    |
| service-intentions  | `intentions:write` |
| service-resolver    | `service:write`    |
| service-router      | `service:write`    |
| service-splitter    | `service:write`    |
| terminating-gateway | `operator:write`   |

The corresponding CLI command is [`consul config write`](/commands/config/write).

### Query Parameters

- `dc` `(string: "")` - Specifies the datacenter to query.
  This parameter defaults to the datacenter of the agent being queried.

- `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. If the index is
  0, Consul will only store the entry if it does not already exist. If the index is
  non-zero, the entry is only set if the current index matches the `ModifyIndex`
  of that entry.

- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the config entry you apply.
  You can also [specify the namespace through other methods](#methods-to-specify-namespace).

### Sample Payload

```json
{
    "Kind": "service-defaults",
    "Name": "web",
    "Protocol": "http"
}
```

### Sample Request

```shell-session
$ curl \
    --request PUT \
    --data @payload \
    http://127.0.0.1:8500/v1/config
```

## Get Configuration

This endpoint returns a specific config entry.

| Method | Path                  | Produces           |
| ------ | --------------------- | ------------------ |
| `GET`  | `/config/:kind/:name` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required               |
| ---------------- | ----------------- | ------------- | -------------------------- |
| `YES`            | `all`             | `none`        | `service:read`<sup>1</sup> |

<sup>1</sup> The ACL required depends on the config entry kind being read:

| Config Entry Kind   | Required ACL      |
| ------------------- | ----------------- |
| ingress-gateway     | `service:read`    |
| proxy-defaults      | `<none>`          |
| service-defaults    | `service:read`    |
| service-intentions  | `intentions:read` |
| service-resolver    | `service:read`    |
| service-router      | `service:read`    |
| service-splitter    | `service:read`    |
| terminating-gateway | `service:read`    |

The corresponding CLI command is [`consul config read`](/commands/config/read).

### Path Parameters

- `kind` `(string: <required>)` - Specifies the kind of the entry to read.

- `name` `(string: <required>)` - Specifies the name of the entry to read.
  The name of the `proxy-defaults` config entry
  must be `global`, and the name of the `mesh` config entry must be `mesh`.

### Query Parameters

- `dc` `(string: "")` - Specifies the datacenter to query.
  This parameter defaults to the datacenter of the agent being queried.

- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the config entry you lookup
  You can also [specify the namespace through other methods](#methods-to-specify-namespace).

### Sample Request

```shell-session
$ curl \
    --request GET \
    http://127.0.0.1:8500/v1/config/service-defaults/web
```

### Sample Response

```json
{
  "Kind": "service-defaults",
  "Name": "web",
  "Protocol": "http",
  "CreateIndex": 15,
  "ModifyIndex": 35
}
```

## List Configurations

This endpoint returns all config entries of the given kind.

@include 'http_api_results_filtered_by_acls.mdx'

| Method | Path            | Produces           |
| ------ | --------------- | ------------------ |
| `GET`  | `/config/:kind` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required               |
| ---------------- | ----------------- | ------------- | -------------------------- |
| `YES`            | `all`             | `none`        | `service:read`<sup>1</sup> |

<sup>1</sup> The ACL required depends on the config entry kind being read:

| Config Entry Kind   | Required ACL      |
| ------------------- | ----------------- |
| ingress-gateway     | `service:read`    |
| proxy-defaults      | `<none>`          |
| service-defaults    | `service:read`    |
| service-intentions  | `intentions:read` |
| service-resolver    | `service:read`    |
| service-router      | `service:read`    |
| service-splitter    | `service:read`    |
| terminating-gateway | `service:read`    |

The corresponding CLI command is [`consul config list`](/commands/config/list).

### Path Parameters

- `kind` `(string: <required>)` - Specifies the kind of the entry to list.

### Query Parameters

- `dc` `(string: "")` - Specifies the datacenter to query.
  This parameter defaults to the datacenter of the agent being queried.

- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the config entries you lookup.
  You can also [specify the namespace through other methods](#methods-to-specify-namespace).

### Sample Request

```shell-session
$ curl \
    --request GET \
    http://127.0.0.1:8500/v1/config/service-defaults
```

### Sample Response

```json
[
  {
    "Kind": "service-defaults",
    "Name": "db",
    "Protocol": "tcp",
    "CreateIndex": 16,
    "ModifyIndex": 16
  },
  {
    "Kind": "service-defaults",
    "Name": "web",
    "Protocol": "http",
    "CreateIndex": 13,
    "ModifyIndex": 13
  }
]
```

## Delete Configuration

This endpoint deletes the given config entry.

| Method   | Path                  | Produces           |
| -------- | --------------------- | ------------------ |
| `DELETE` | `/config/:kind/:name` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                                      |
| ---------------- | ----------------- | ------------- | ------------------------------------------------- |
| `NO`             | `none`            | `none`        | `service:write`<br />`operator:write`<sup>1</sup> |

<sup>1</sup> The ACL required depends on the config entry kind being deleted:

| Config Entry Kind   | Required ACL       |
| ------------------- | ------------------ |
| ingress-gateway     | `operator:write`   |
| proxy-defaults      | `operator:write`   |
| service-defaults    | `service:write`    |
| service-intentions  | `intentions:write` |
| service-resolver    | `service:write`    |
| service-router      | `service:write`    |
| service-splitter    | `service:write`    |
| terminating-gateway | `operator:write `  |

The corresponding CLI command is [`consul config delete`](/commands/config/delete).

### Path Parameters

- `kind` `(string: <required>)` - Specifies the kind of the entry to delete.

- `name` `(string: <required>)` - Specifies the name of the entry to delete.
  The name of the `proxy-defaults` config entry
  must be `global`, and the name of the `mesh` config entry must be `mesh`.

### Query Parameters

- `dc` `(string: "")` - Specifies the datacenter to query.
  This parameter defaults to the datacenter of the agent being queried.

- `cas` `(int: 0)` - Specifies to use a Check-And-Set operation. Unlike `PUT`,
  the index must be greater than 0 for Consul to take any action: a 0 index will
  not delete the config entry. If the index is non-zero, the config entry is only
  deleted if the index matches the `ModifyIndex` of that config entry.

- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the config entry you delete.
  You can also [specify the namespace through other methods](#methods-to-specify-namespace).

### Sample Request

```shell-session
$ curl \
    --request DELETE \
    http://127.0.0.1:8500/v1/config/service-defaults/web
```

## Methods to Specify Namespace <EnterpriseAlert inline />

Config endpoints
support several methods for specifying the namespace of configuration entry resources
with the following order of precedence:
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace