--- 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](/consul/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](/consul/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](/consul/api-docs/features/blocking), [consistency modes](/consul/api-docs/features/consistency), [agent caching](/consul/api-docs/features/caching), and [required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------------------------- | | `NO` | `none` | `none` | Refer to [Permissions](#permissions) | The corresponding CLI command is [`consul config write`](/consul/commands/config/write). ### Permissions The ACL required depends on the config entry being written: | Config Entry Kind | Required ACLs | | ----------------------- | -------------------------------- | | api-gateway | `mesh:write` or `operator:write` | | bound-api-gateway | Not writable. | | exported-services | `mesh:write` or `operator:write` | | file-system-certificate | `mesh:write` or `operator:write` | | http-route | `mesh:write` or `operator:write` | | ingress-gateway | `mesh:write` or `operator:write` | | inline-certificate | `mesh:write` or `operator:write` | | mesh | `mesh:write` or `operator:write` | | proxy-defaults | `mesh:write` or `operator:write` | | service-defaults | `service:write` | | service-intentions | `intentions:write` | | service-resolver | `service:write` | | service-router | `service:write` | | service-splitter | `service:write` | | tcp-route | `mesh:write` or `operator:write` | | terminating-gateway | `mesh:write` or `operator: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). @include 'http-api-query-parms-partition.mdx' ### 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](/consul/api-docs/features/blocking), [consistency modes](/consul/api-docs/features/consistency), [agent caching](/consul/api-docs/features/caching), and [required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------------------------------- | | `YES` | `all` | `none` | Refer to [Permissions](#permissions-1) | The corresponding CLI command is [`consul config read`](/consul/commands/config/read). ### Permissions The ACL required depends on the config entry kind being read: | Config Entry Kind | Required ACLs | | ----------------------- | -------------------------------- | | api-gateway | `service:read` | | bound-api-gateway | `service:read` | | exported-services | `mesh:read` or `operator:read` | | file-system-certificate | `mesh:read` or `operator:read` | | http-route | `mesh:read` or `operator:read` | | ingress-gateway | `service:read` | | inline-certificate | `mesh:read` or `operator:read` | | mesh | No ACL required | | proxy-defaults | No ACL required | | service-defaults | `service:read` | | service-intentions | `intentions:read` | | service-resolver | `service:read` | | service-router | `service:read` | | service-splitter | `service:read` | | tcp-route | `mesh:read` or `operator:read` | | terminating-gateway | `service: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). @include 'http-api-query-parms-partition.mdx' ### 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](/consul/api-docs/features/blocking), [consistency modes](/consul/api-docs/features/consistency), [agent caching](/consul/api-docs/features/caching), and [required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------------------------------- | | `YES` | `all` | `none` | Refer to [Permissions](#permissions-2) | ### Permissions The ACL required depends on the config entry kind being read: | Config Entry Kind | Required ACLs | | ----------------------- | -------------------------------- | | api-gateway | `service:read` | | bound-api-gateway | `service:read` | | exported-services | `mesh:read` or `operator:read` | | file-system-certificate | `mesh:read` or `operator:read` | | http-route | `mesh:read` or `operator:read` | | ingress-gateway | `service:read` | | inline-certificate | `mesh:read` or `operator:read` | | mesh | No ACL required | | proxy-defaults | No ACL required | | service-defaults | `service:read` | | service-intentions | `intentions:read` | | service-resolver | `service:read` | | service-router | `service:read` | | service-splitter | `service:read` | | tcp-route | `mesh:read` or `operator:read` | | terminating-gateway | `service:read` | The corresponding CLI command is [`consul config list`](/consul/commands/config/list). ### Path Parameters - `kind` `(string: <required>)` - Specifies the kind of the entry to list. - `filter` `(string: "")` - Specifies an expression to use for filtering the results. ### 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). @include 'http-api-query-parms-partition.mdx' ### 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](/consul/api-docs/features/blocking), [consistency modes](/consul/api-docs/features/consistency), [agent caching](/consul/api-docs/features/caching), and [required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------------------------- | | `NO` | `none` | `none` | Refer to [Permissions](#permissions-3) | ### Permissions The ACL required depends on the config entry kind being deleted: | Config Entry Kind | Required ACLs | | ----------------------- | -------------------------------- | | api-gateway | `mesh:write` or `operator:write` | | bound-api-gateway | Not writable. | | exported-services | `mesh:write` or `operator:write` | | file-system-certificate | `mesh:write` or `operator:write` | | http-route | `mesh:write` or `operator:write` | | ingress-gateway | `mesh:write` or `operator:write` | | inline-certificate | `mesh:write` or `operator:write` | | mesh | `mesh:write` or `operator:write` | | proxy-defaults | `mesh:write` or `operator:write` | | service-defaults | `service:write` | | service-intentions | `intentions:write` | | service-resolver | `service:write` | | service-router | `service:write` | | service-splitter | `service:write` | | tcp-route | `mesh:write` or `operator:write` | | terminating-gateway | `mesh:write` or `operator:write` | The corresponding CLI command is [`consul config delete`](/consul/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). @include 'http-api-query-parms-partition.mdx' ### 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