»Config HTTP Endpoint

The /config endpoints create, update, delete and query central configuration entries registered with Consul. See the agent configuration for more information on how to enable this functionality for centrally configuring services and configuration entries docs 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, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`none`	`none`	`service:write` `operator:write`¹

¹ The ACL required depends on the config entry kind being updated:

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.

»Parameters

dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. This is specified as part of the URL as a query parameter.
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: "")
Enterprise
- Specifies the namespace the config entry will apply to. This value may be provided by either the ns URL query parameter or in the X-Consul-Namespace header. If not provided, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

»Sample Payload

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

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

»Sample Request

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

$ 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, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`YES`	`all`	`none`	`service:read`¹

¹ 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.

»Parameters

dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. This is specified as part of the URL as a query parameter.
kind (string: <required>) - Specifies the kind of the entry to read. This is specified as part of the URL.
name (string: <required>) - Specifies the name of the entry to read. This is specified as part of the URL. The name of the proxy-defaults config entry must be global, and the name of the mesh config entry must be mesh.
ns (string: "")
Enterprise
- Specifies the namespace to query. This value may be provided by either the ns URL query parameter or in the X-Consul-Namespace header. If not provided, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

»Sample Request

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

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

»Sample Response

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

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

»List Configurations

This endpoint returns all config entries of the given kind.

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

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`YES`	`all`	`none`	`service:read`¹

¹ 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.

»Parameters

dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. This is specified as part of the URL as a query parameter.
kind (string: <required>) - Specifies the kind of the entry to list. This is specified as part of the URL.
ns (string: "")
Enterprise
- Specifies the namespace to query. This value may be provided by either the ns URL query parameter or in the X-Consul-Namespace header. If not provided, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

»Sample Request

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

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

»Sample Response

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

[  {    "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, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`none`	`none`	`service:write` `operator:write`¹

¹ 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.

»Parameters

dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried. This is specified as part of the URL as a query parameter.
kind (string: <required>) - Specifies the kind of the entry to delete. This is specified as part of the URL.
name (string: <required>) - Specifies the name of the entry to delete. This is specified as part of the URL. The name of the proxy-defaults config entry must be global, and the name of the mesh config entry must be mesh.
ns (string: "")
Enterprise
- Specifies the namespace to delete from. This value may be provided by either the ns URL query parameter or in the X-Consul-Namespace header. If not provided, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.
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. This is specified as part of the URL as a query parameter.

»Sample Request

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

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