• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Consul
  • Install
  • Tutorials
  • Documentation
  • API
  • CLI
  • Try Cloud(opens in new tab)
  • Sign up
Consul Home

API

Skip to main content
  • API
  • API Structure

  • Admin Partitions
  • Catalog
  • Cluster Peering
  • Config
  • Coordinates
  • Discovery Chain
  • Events
  • Health
  • KV Store
  • Namespaces
  • Prepared Queries
  • Sessions
  • Snapshots
  • Status
  • Transactions

  • Libraries & SDKs

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Consul
  3. API
  4. Catalog
  • Consul
  • v1.13.x
  • v1.12.x
  • v1.11.x
  • v1.10.x
  • v1.9.x
  • v1.8.x

ยปCatalog HTTP API

The /catalog endpoints register and deregister nodes, services, and checks in Consul. The catalog should not be confused with the agent, since some of the API methods look similar.

Register Entity

This endpoint is a low-level mechanism for registering or updating entries in the catalog. It is usually preferable to instead use the agent endpoints for registration as they are simpler and perform anti-entropy.

MethodPathProduces
PUT/catalog/registerapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenonenode:write,service:write

Query Parameters

  • ns (string: "")
    Enterprise
    - Specifies the namespace of the service and checks you register. You can also specify the namespace through other methods.

JSON Request Body Schema

  • ID (string: "") - An optional UUID to assign to the node. This must be a 36-character UUID-formatted string.

  • Node (string: <required>) - Specifies the node ID to register.

  • Address (string: <required>) - Specifies the address to register.

  • Datacenter (string: "") - Specifies the datacenter, which defaults to the agent's datacenter if not provided.

  • TaggedAddresses (map<string|string>: nil) - Specifies the tagged addresses.

  • NodeMeta (map<string|string>: nil) - Specifies arbitrary KV metadata pairs for filtering purposes.

  • Service (Service: nil) - Specifies to register a service. If ID is not provided, it will be defaulted to the value of the Service.Service property. Only one service with a given ID may be present per node. We recommend using valid DNS labels for service definition names for compatibility with external DNS. The service Tags, Address, Meta, and Port fields are all optional. For more information about these fields and the implications of setting them, see the Service - Agent API page as registering services differs between using this or the Services Agent endpoint.

  • Check (Check: nil) - Specifies to register a check. The register API manipulates the health check entry in the Catalog, but it does not setup the script, TTL, or HTTP check to monitor the node's health. To truly enable a new health check, the check must either be provided in agent configuration or set via the agent endpoint.

    The CheckID can be omitted and will default to the value of Name. As with Service.ID, the CheckID must be unique on this node. Notes is an opaque field that is meant to hold human-readable text. If a ServiceID is provided that matches the ID of a service on that node, the check is treated as a service level health check, instead of a node level health check. The Status must be one of passing, warning, or critical.

    The Definition field can be provided with details for a TCP or HTTP health check. For more information, see the Health Checks page.

    Multiple checks can be provided by replacing Check with Checks and sending an array of Check objects.

  • SkipNodeUpdate (bool: false) - Specifies whether to skip updating the node's information in the registration. This is useful in the case where only a health check or service entry on a node needs to be updated or when a register request is intended to update a service entry or health check. In both use cases, node information will not be overwritten, if the node is already registered. Note, if the parameter is enabled for a node that doesn't exist, it will still be created.

  • Namespace (string: "")

    Enterprise
    - Specifies the namespace of the service and checks you register. This field takes precedence over the ns query parameter, one of several other methods to specify the namespace.

It is important to note that Check does not have to be provided with Service and vice versa. A catalog entry can have either, neither, or both.

Sample Payload

{
  "Datacenter": "dc1",
  "ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
  "Node": "t2.320",
  "Address": "192.168.10.10",
  "TaggedAddresses": {
    "lan": "192.168.10.10",
    "wan": "10.0.10.10"
  },
  "NodeMeta": {
    "somekey": "somevalue"
  },
  "Service": {
    "ID": "redis1",
    "Service": "redis",
    "Tags": ["primary", "v1"],
    "Address": "127.0.0.1",
    "TaggedAddresses": {
      "lan": {
        "address": "127.0.0.1",
        "port": 8000
      },
      "wan": {
        "address": "198.18.0.1",
        "port": 80
      }
    },
    "Meta": {
      "redis_version": "4.0"
    },
    "Port": 8000,
    "Namespace": "default"
  },
  "Check": {
    "Node": "t2.320",
    "CheckID": "service:redis1",
    "Name": "Redis health check",
    "Notes": "Script based health check",
    "Status": "passing",
    "ServiceID": "redis1",
    "Definition": {
      "TCP": "localhost:8888",
      "Interval": "5s",
      "Timeout": "1s",
      "DeregisterCriticalServiceAfter": "30s"
    },
    "Namespace": "default"
  },
  "SkipNodeUpdate": false
}

Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    --header "X-Consul-Namespace: team-1" \
    http://127.0.0.1:8500/v1/catalog/register

Deregister Entity

This endpoint is a low-level mechanism for directly removing entries from the Catalog. It is usually preferable to instead use the agent endpoints for deregistration as they are simpler and perform anti-entropy.

MethodPathProduces
PUT/catalog/deregisterapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenonenode:write,service:write

Query Parameters

  • ns (string: "")
    Enterprise
    - Specifies the namespace of the service and checks you deregister. You can also specify the namespace through other methods.

JSON Request Body Schema

The behavior of the endpoint depends on what keys are provided.

  • Node (string: <required>) - Specifies the ID of the node. If no other values are provided, this node, all its services, and all its checks are removed.

  • Datacenter (string: "") - Specifies the datacenter, which defaults to the agent's datacenter if not provided.

  • CheckID (string: "") - Specifies the ID of the check to remove.

  • ServiceID (string: "") - Specifies the ID of the service to remove. The service and all associated checks will be removed.

  • Namespace (string: "")

    Enterprise
    - Specifies the namespace of the service and checks you deregister. This field takes precedence over the ns query parameter, one of several other methods to specify the namespace. You can also specify the namespace in the Service or Check fields; if namespaces are specified in multiple places, they must all be the same.

Sample Payloads

{
  "Datacenter": "dc1",
  "Node": "t2.320"
}
{
  "Datacenter": "dc1",
  "Node": "t2.320",
  "CheckID": "service:redis1",
  "Namespace": "team-1"
}
{
  "Datacenter": "dc1",
  "Node": "t2.320",
  "ServiceID": "redis1",
  "Namespace": "team-1"
}

Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/catalog/deregister

List Datacenters

This endpoint returns the list of all known datacenters. The datacenters will be sorted in ascending order based on the estimated median round trip time from the server to the servers in that datacenter.

This endpoint does not require a cluster leader and will succeed even during an availability outage. Therefore, it can be used as a simple check to see if any Consul servers are routable.

MethodPathProduces
GET/catalog/datacentersapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonesimplenone

The corresponding CLI command is consul catalog datacenters.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/catalog/datacenters

Sample Response

["dc1", "dc2"]

List Nodes

This endpoint and returns the nodes registered in a given datacenter.

The HTTP response includes the X-Consul-Results-Filtered-By-ACLs: true header if the response array excludes results due to ACL policy configuration. Refer to the HTTP API documentation for more information.

MethodPathProduces
GET/catalog/nodesapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnonenode:read

The corresponding CLI command is consul catalog nodes.

Query Parameters

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

  • near (string: "") - Specifies a node name to sort the node list in ascending order based on the estimated round trip time from that node. Passing ?near=_agent uses the agent's node for the sort.

  • node-meta (string: "") Deprecated - Use filter with the Meta selector instead. This parameter will be removed in a future version of Consul. Specifies a desired node metadata key/value pair of the form key:value. This parameter can be specified multiple times, and filters the results to nodes with the specified key/value pairs.

  • filter (string: "") - Specifies the expression used to filter the queries results prior to returning the data.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/catalog/nodes

Sample Response

[
  {
    "ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
    "Node": "baz",
    "Address": "10.1.10.11",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "10.1.10.11",
      "wan": "10.1.10.11"
    },
    "Meta": {
      "instance_type": "t2.medium"
    }
  },
  {
    "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
    "Node": "t2.320",
    "Address": "10.1.10.12",
    "Datacenter": "dc2",
    "TaggedAddresses": {
      "lan": "10.1.10.11",
      "wan": "10.1.10.12"
    },
    "Meta": {
      "instance_type": "t2.large"
    }
  }
]

Filtering

The filter will be executed against each Node in the result list with the following selectors and filter operations being supported:

SelectorSupported Operations
AddressEqual, Not Equal, In, Not In, Matches, Not Matches
DatacenterEqual, Not Equal, In, Not In, Matches, Not Matches
IDEqual, Not Equal, In, Not In, Matches, Not Matches
MetaIs Empty, Is Not Empty, In, Not In
Meta.<any>Equal, Not Equal, In, Not In, Matches, Not Matches
NodeEqual, Not Equal, In, Not In, Matches, Not Matches
TaggedAddressesIs Empty, Is Not Empty, In, Not In
TaggedAddresses.<any>Equal, Not Equal, In, Not In, Matches, Not Matches

List Services

This endpoint returns the services registered in a given datacenter.

The HTTP response includes the X-Consul-Results-Filtered-By-ACLs: true header if the response array excludes results due to ACL policy configuration. Refer to the HTTP API documentation for more information.

MethodPathProduces
GET/catalog/servicesapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallbackground refreshservice:read

The corresponding CLI command is consul catalog services.

Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried.

  • node-meta (string: "") Deprecated - Use filter with the NodeMeta selector instead. This parameter will be removed in a future version of Consul. Specifies a desired node metadata key/value pair of the form key:value. This parameter can be specified multiple times, and filters the results to nodes with the specified key/value pairs.

  • ns (string: "")

    Enterprise
    - Specifies the namespace of the services you lookup. You can also specify the namespace through other methods.

  • filter (string: "") - Specifies the expression used to filter the queries results prior to returning the data.

Filtering

The filter will be executed against each Service mapping within the catalog. The following selectors and filter operations are supported:

SelectorSupported Operations
AddressEqual, Not Equal, In, Not In, Matches, Not Matches
DatacenterEqual, Not Equal, In, Not In, Matches, Not Matches
IDEqual, Not Equal, In, Not In, Matches, Not Matches
NodeEqual, Not Equal, In, Not In, Matches, Not Matches
NodeMeta.<any>Equal, Not Equal, In, Not In, Matches, Not Matches
NodeMetaIs Empty, Is Not Empty, In, Not In
ServiceAddressEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceConnect.NativeEqual, Not Equal
ServiceEnableTagOverrideEqual, Not Equal
ServiceIDEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceKindEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceMeta.<any>Equal, Not Equal, In, Not In, Matches, Not Matches
ServiceMetaIs Empty, Is Not Empty, In, Not In
ServiceNameEqual, Not Equal, In, Not In, Matches, Not Matches
ServicePortEqual, Not Equal
ServiceProxy.DestinationServiceIDEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.DestinationServiceNameEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.LocalServiceAddressEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.LocalServicePortEqual, Not Equal
ServiceProxy.ModeEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.TransparentProxy.OutboundListenerPortEqual, Not Equal
ServiceProxy.MeshGateway.ModeEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.Upstreams.DatacenterEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.Upstreams.DestinationNameEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.Upstreams.DestinationNamespaceEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.Upstreams.DestinationTypeEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.Upstreams.LocalBindAddressEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.Upstreams.LocalBindPortEqual, Not Equal
ServiceProxy.Upstreams.MeshGateway.ModeEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.UpstreamsIs Empty, Is Not Empty
ServiceTaggedAddresses.<any>.AddressEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceTaggedAddresses.<any>.PortEqual, Not Equal
ServiceTaggedAddressesIs Empty, Is Not Empty, In, Not In
ServiceTagsIn, Not In, Is Empty, Is Not Empty
ServiceWeights.PassingEqual, Not Equal
ServiceWeights.WarningEqual, Not Equal
TaggedAddresses.<any>Equal, Not Equal, In, Not In, Matches, Not Matches
TaggedAddressesIs Empty, Is Not Empty, In, Not In

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/catalog/services?ns=foo

Sample Response

{
  "consul": [],
  "redis": [],
  "postgresql": ["primary", "secondary"]
}

The keys are the service names, and the array values provide all known tags for a given service.

List Nodes for Service

This endpoint returns the nodes providing a service in a given datacenter.

The HTTP response includes the X-Consul-Results-Filtered-By-ACLs: true header if the response array excludes results due to ACL policy configuration. Refer to the HTTP API documentation for more information.

MethodPathProduces
GET/catalog/service/:service_nameapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallbackground refreshnode:read,service:read

Path Parameters

  • service_name (string: <required>) - Specifies the name of the service for which to list nodes.

Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried.

  • tag (string: "") Deprecated - Use filter with the ServiceTags selector instead. This parameter will be removed in a future version of Consul. Specifies the tag to filter on. Can be used multiple times for additional filtering, returning only the results that include all of the tag values provided.

  • near (string: "") - Specifies a node name to sort the node list in ascending order based on the estimated round trip time from that node. Passing ?near=_agent uses the agent's node for the sort.

  • node-meta (string: "") Deprecated - Use filter with the NodeMeta selector instead. This parameter will be removed in a future version of Consul. Specifies a desired node metadata key/value pair of the form key:value. This parameter can be specified multiple times, and filters the results to nodes with the specified key/value pairs.

  • filter (string: "") - Specifies the expression used to filter the queries results prior to returning the data.

  • merge-central-config - Include this flag in a request for connect-proxy kind or *-gateway kind services to return a fully resolved service definition that includes merged values from the proxy-defaults/global and service-defaults/:service config entries. Returning a fully resolved service definition is useful when a service was registered using the /catalog/register endpoint, which does not automatically merge config entries.

  • ns (string: "")

    Enterprise
    - Specifies the namespace of the services you lookup. You can also specify the namespace through other methods.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/catalog/service/web?ns=default

Sample Response

[
  {
    "ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
    "Node": "t2.320",
    "Address": "192.168.10.10",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "192.168.10.10",
      "wan": "10.0.10.10"
    },
    "NodeMeta": {
      "somekey": "somevalue"
    },
    "CreateIndex": 51,
    "ModifyIndex": 51,
    "ServiceAddress": "172.17.0.3",
    "ServiceEnableTagOverride": false,
    "ServiceID": "32a2a47f7992:nodea:5000",
    "ServiceName": "web",
    "ServicePort": 5000,
    "ServiceMeta": {
      "web_meta_value": "baz"
    },
    "ServiceTaggedAddresses": {
      "lan": {
        "address": "172.17.0.3",
        "port": 5000
      },
      "wan": {
        "address": "198.18.0.1",
        "port": 512
      }
    },
    "ServiceTags": ["prod"],
    "ServiceProxy": {
      "DestinationServiceName": "",
      "DestinationServiceID": "",
      "LocalServiceAddress": "",
      "LocalServicePort": 0,
      "Config": null,
      "Upstreams": null
    },
    "ServiceConnect": {
      "Native": false,
      "Proxy": null
    },
    "Namespace": "default"
  }
]
  • Address is the IP address of the Consul node on which the service is registered.

  • Datacenter is the data center of the Consul node on which the service is registered.

  • TaggedAddresses is the list of explicit LAN and WAN IP addresses for the agent

  • NodeMeta is a list of user-defined metadata key/value pairs for the node

  • CreateIndex is an internal index value representing when the service was created

  • ModifyIndex is the last index that modified the service

  • Node is the name of the Consul node on which the service is registered

  • ServiceAddress is the IP address of the service host โ€” if empty, node address should be used

  • ServiceEnableTagOverride indicates whether service tags can be overridden on this service

  • ServiceID is a unique service instance identifier

  • ServiceName is the name of the service

  • ServiceMeta is a list of user-defined metadata key/value pairs for the service

  • ServicePort is the port number of the service

  • ServiceTags is a list of tags for the service

  • ServiceTaggedAddresses is the map of explicit LAN and WAN addresses for the service instance. This includes both the address as well as the port.

  • ServiceKind is the kind of service, usually "". See the Agent service registration API for more information.

  • ServiceProxy is the proxy config as specified in Connect Proxies.

  • ServiceConnect are the Connect settings. The value of this struct is equivalent to the Connect field for service registration.

  • Namespace is the Consul Enterprise namespace of this service instance

Filtering

Filtering is executed against each entry in the top level result list with the following selectors and filter operations being supported:

SelectorSupported Operations
AddressEqual, Not Equal, In, Not In, Matches, Not Matches
DatacenterEqual, Not Equal, In, Not In, Matches, Not Matches
IDEqual, Not Equal, In, Not In, Matches, Not Matches
NodeEqual, Not Equal, In, Not In, Matches, Not Matches
NodeMeta.<any>Equal, Not Equal, In, Not In, Matches, Not Matches
NodeMetaIs Empty, Is Not Empty, In, Not In
ServiceAddressEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceConnect.NativeEqual, Not Equal
ServiceEnableTagOverrideEqual, Not Equal
ServiceIDEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceKindEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceMeta.<any>Equal, Not Equal, In, Not In, Matches, Not Matches
ServiceMetaIs Empty, Is Not Empty, In, Not In
ServiceNameEqual, Not Equal, In, Not In, Matches, Not Matches
ServicePortEqual, Not Equal
ServiceProxy.DestinationServiceIDEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.DestinationServiceNameEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.LocalServiceAddressEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.LocalServicePortEqual, Not Equal
ServiceProxy.ModeEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.TransparentProxy.OutboundListenerPortEqual, Not Equal
ServiceProxy.MeshGateway.ModeEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.Upstreams.DatacenterEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.Upstreams.DestinationNameEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.Upstreams.DestinationNamespaceEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.Upstreams.DestinationTypeEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.Upstreams.LocalBindAddressEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.Upstreams.LocalBindPortEqual, Not Equal
ServiceProxy.Upstreams.MeshGateway.ModeEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceProxy.UpstreamsIs Empty, Is Not Empty
ServiceTaggedAddresses.<any>.AddressEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceTaggedAddresses.<any>.PortEqual, Not Equal
ServiceTaggedAddressesIs Empty, Is Not Empty, In, Not In
ServiceTagsIn, Not In, Is Empty, Is Not Empty
ServiceWeights.PassingEqual, Not Equal
ServiceWeights.WarningEqual, Not Equal
TaggedAddresses.<any>Equal, Not Equal, In, Not In, Matches, Not Matches
TaggedAddressesIs Empty, Is Not Empty, In, Not In

List Nodes for Connect-capable Service

This endpoint returns the nodes providing a Connect-capable service in a given datacenter. This will include both proxies and native integrations. A service may register both Connect-capable and incapable services at the same time, so this endpoint may be used to filter only the Connect-capable endpoints.

The HTTP response includes the X-Consul-Results-Filtered-By-ACLs: true header if the response array excludes results due to ACL policy configuration. Refer to the HTTP API documentation for more information.

MethodPathProduces
GET/catalog/connect/:serviceapplication/json

Parameters and response format are the same as /catalog/service/:service_name.

Retrieve Map of Services for a Node

This endpoint returns the node's registered services.

The HTTP response includes the X-Consul-Results-Filtered-By-ACLs: true header if the response array excludes results due to ACL policy configuration. Refer to the HTTP API documentation for more information.

MethodPathProduces
GET/catalog/node/:node_nameapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnonenode:read,service:read

Path Parameters

  • node_name (string: <required>) - Specifies the name of the node to list services for.

Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried.

  • filter (string: "") - Specifies the expression used to filter the queries results prior to returning the data.

  • ns (string: "")

    Enterprise
    - Specifies the namespace of the services you lookup. You can also specify the namespace through other methods.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/catalog/node/my-node

Sample Response

{
  "Node": {
    "ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
    "Node": "t2-node",
    "Address": "10.1.10.12",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "10.1.10.12",
      "wan": "10.1.10.12"
    },
    "Meta": {
      "instance_type": "t2.medium"
    }
  },
  "Services": {
    "consul": {
      "ID": "consul",
      "Service": "consul",
      "Tags": null,
      "Meta": {},
      "Port": 8300
    },
    "redis": {
      "ID": "redis",
      "Service": "redis",
      "TaggedAddresses": {
        "lan": {
          "address": "10.1.10.12",
          "port": 8000
        },
        "wan": {
          "address": "198.18.1.2",
          "port": 80
        }
      },
      "Tags": ["v1"],
      "Meta": {
        "redis_version": "4.0"
      },
      "Port": 8000,
      "Namespace": "default"
    }
  }
}

Filtering

The filter will be executed against each value in the Services mapping within the top level Node object. The following selectors and filter operations are supported:

SelectorSupported Operations
AddressEqual, Not Equal, In, Not In, Matches, Not Matches
Connect.NativeEqual, Not Equal
EnableTagOverrideEqual, Not Equal
IDEqual, Not Equal, In, Not In, Matches, Not Matches
KindEqual, Not Equal, In, Not In, Matches, Not Matches
MetaIs Empty, Is Not Empty, In, Not In
Meta.<any>Equal, Not Equal, In, Not In, Matches, Not Matches
PortEqual, Not Equal
Proxy.DestinationServiceIDEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.DestinationServiceNameEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.LocalServiceAddressEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.LocalServicePortEqual, Not Equal
Proxy.ModeEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.TransparentProxy.OutboundListenerPortEqual, Not Equal
Proxy.MeshGateway.ModeEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.UpstreamsIs Empty, Is Not Empty
Proxy.Upstreams.DatacenterEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.Upstreams.DestinationNameEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.Upstreams.DestinationNamespaceEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.Upstreams.DestinationTypeEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.Upstreams.LocalBindAddressEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.Upstreams.LocalBindPortEqual, Not Equal
Proxy.Upstreams.MeshGateway.ModeEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceEqual, Not Equal, In, Not In, Matches, Not Matches
TaggedAddressesIs Empty, Is Not Empty, In, Not In
TaggedAddresses.<any>.AddressEqual, Not Equal, In, Not In, Matches, Not Matches
TaggedAddresses.<any>.PortEqual, Not Equal
TagsIn, Not In, Is Empty, Is Not Empty
Weights.PassingEqual, Not Equal
Weights.WarningEqual, Not Equal

List Services for Node

This endpoint returns the node's registered services.

The HTTP response includes the X-Consul-Results-Filtered-By-ACLs: true header if the response array excludes results due to ACL policy configuration. Refer to the HTTP API documentation for more information.

MethodPathProduces
GET/catalog/node-services/:node_nameapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnonenode:read,service:read

Path Parameters

  • node_name (string: <required>) - Specifies the name of the node to list services for.

Query Parameters

  • dc (string: "") - Specifies the datacenter to query. This will default to the datacenter of the agent being queried.

  • filter (string: "") - Specifies the expression used to filter the queries results prior to returning the data.

  • merge-central-config - Include this flag in a request for connect-proxy kind or *-gateway kind services to return a fully resolved service definition that includes merged values from the proxy-defaults/global and service-defaults/:service config entries. Returning a fully resolved service definition is useful when a service was registered using the /catalog/register endpoint, which does not automatically merge config entries.

  • ns (string: "")

    Enterprise
    - Specifies the namespace of the services you lookup. The namespace may be specified as '*' to return results for all namespaces. You can also specify the namespace through other methods.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/catalog/node-services/t2-node

Sample Response

{
  "Node": {
    "ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
    "Node": "t2-node",
    "Address": "10.1.10.12",
    "Datacenter": "dc1",
    "TaggedAddresses": {
      "lan": "10.1.10.12",
      "wan": "10.1.10.12"
    },
    "Meta": {
      "instance_type": "t2.medium"
    }
  },
  "Services": [
    {
      "ID": "consul",
      "Service": "consul",
      "Tags": null,
      "Meta": {},
      "Port": 8300
    },
    {
      "ID": "redis",
      "Service": "redis",
      "TaggedAddresses": {
        "lan": {
          "address": "10.1.10.12",
          "port": 8000
        },
        "wan": {
          "address": "198.18.1.2",
          "port": 80
        }
      },
      "Tags": [
        "v1"
      ],
      "Meta": {
        "redis_version": "4.0"
      },
      "Port": 8000,
      "Namespace": "default"
    }
  }
}

Filtering

The filter will be executed against each value in the Services list within the top level object. The following selectors and filter operations are supported:

SelectorSupported Operations
AddressEqual, Not Equal, In, Not In, Matches, Not Matches
Connect.NativeEqual, Not Equal
EnableTagOverrideEqual, Not Equal
IDEqual, Not Equal, In, Not In, Matches, Not Matches
KindEqual, Not Equal, In, Not In, Matches, Not Matches
MetaIs Empty, Is Not Empty, In, Not In
Meta.<any>Equal, Not Equal, In, Not In, Matches, Not Matches
PortEqual, Not Equal
Proxy.DestinationServiceIDEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.DestinationServiceNameEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.LocalServiceAddressEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.LocalServicePortEqual, Not Equal
Proxy.ModeEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.TransparentProxy.OutboundListenerPortEqual, Not Equal
Proxy.MeshGateway.ModeEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.UpstreamsIs Empty, Is Not Empty
Proxy.Upstreams.DatacenterEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.Upstreams.DestinationNameEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.Upstreams.DestinationNamespaceEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.Upstreams.DestinationTypeEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.Upstreams.LocalBindAddressEqual, Not Equal, In, Not In, Matches, Not Matches
Proxy.Upstreams.LocalBindPortEqual, Not Equal
Proxy.Upstreams.MeshGateway.ModeEqual, Not Equal, In, Not In, Matches, Not Matches
ServiceEqual, Not Equal, In, Not In, Matches, Not Matches
TaggedAddressesIs Empty, Is Not Empty, In, Not In
TaggedAddresses.<any>.AddressEqual, Not Equal, In, Not In, Matches, Not Matches
TaggedAddresses.<any>.PortEqual, Not Equal
TagsIn, Not In, Is Empty, Is Not Empty
Weights.PassingEqual, Not Equal
Weights.WarningEqual, Not Equal

List Services for Gateway

1.8.0+: This API is available in Consul versions 1.8.0 and later.

This endpoint returns the services associated with an ingress gateway or terminating gateway.

The HTTP response includes the X-Consul-Results-Filtered-By-ACLs: true header if the response array excludes results due to ACL policy configuration. Refer to the HTTP API documentation for more information.

MethodPathProduces
GET/catalog/gateway-services/:gatewayapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnoneservice:read

Path Parameters

  • gateway (string: <required>) - Specifies the name of the node to list services for.

Query Parameters

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

  • ns (string: "")

    Enterprise
    - Specifies the namespace of the services you lookup. The namespace may be specified as '*' to return results for all namespaces. You can also specify the namespace through other methods.

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/catalog/gateway-services/my-terminating-gateway

Sample Responses

[
  {
    "Gateway": {
      "Name": "my-terminating-gateway",
      "Namespace": "default"
    },
    "Service": {
      "Name": "api",
      "Namespace": "frontend"
    },
    "GatewayKind": "terminating-gateway",
    "CAFile": "/etc/certs/ca.pem",
    "CertFile": "/etc/certs/api/client.pem",
    "KeyFile": "/etc/certs/api/client.key",
    "SNI": "api.my-domain",
    "CreateIndex": 16,
    "ModifyIndex": 16
  },
  {
    "Gateway": {
      "Name": "my-terminating-gateway",
      "Namespace": "default"
    },
    "Service": {
      "Name": "web",
      "Namespace": "frontend"
    },
    "GatewayKind": "terminating-gateway",
    "CreateIndex": 17,
    "ModifyIndex": 17
  }
]
[
  {
    "Gateway": {
      "Name": "my-ingress-gateway",
      "Namespace": "default"
    },
    "Service": {
      "Name": "api",
      "Namespace": "frontend"
    },
    "GatewayKind": "ingress-gateway",
    "Port": 8888,
    "Protocol": "http",
    "Hosts": ["api.mydomain.com"],
    "CreateIndex": 15,
    "ModifyIndex": 15
  },
  {
    "Gateway": {
      "Name": "my-ingress-gateway",
      "Namespace": "default"
    },
    "Service": {
      "Name": "redis",
      "Namespace": "ops"
    },
    "GatewayKind": "ingress-gateway",
    "Port": 8443,
    "Protocol": "tcp",
    "CreateIndex": 16,
    "ModifyIndex": 16
  }
]
  • Gateway.Name is the name of the gateway service of the request

  • Gateway.Namespace is the Consul Enterprise namespace of the gateway

  • Service.Name is the name of a service associated with the gateway

  • Service.Namespace is the Consul Enterprise namespace of a service associated with the gateway

  • GatewayKind is the kind of service, will be one of "ingress-gateway" or "terminating-gateway". See the Agent service registration API for more information.

  • CAFile is the path to a CA file the gateway will use for TLS origination to the associated service

  • CertFile is the path to a client certificate the gateway will use for TLS origination to the associated service

  • KeyFile is the path to a key file the gateway will use for TLS origination to the associated service

  • SNI is a hostname or domain name the gateway will specify during the TLS handshake with the associated service

  • Port is the port the ingress gateway is listening on for the associated service

  • Protocol is the protocol of the ingress gateway's listener for the associated service

  • Hosts list of hosts that specify what requests will match to this associated service

  • FromWildcard determines whether the service was associated with the gateway by providing a wildcard specifier in the gateway's configuration entry

Methods to Specify Namespace
Enterprise

Catalog endpoints support several methods for specifying the namespace of resources with the following order of precedence:

  1. Namespace field of the JSON request body - only applies to the register entity endpoint
  2. ns query parameter
  3. X-Consul-Namespace request header
  4. Namespace is inherited from the namespace of the request's ACL token (if any)
  5. The default namespace
Edit this page on GitHub

On this page

  1. Catalog HTTP API
  2. Register Entity
  3. Deregister Entity
  4. List Datacenters
  5. List Nodes
  6. List Services
  7. List Nodes for Service
  8. List Nodes for Connect-capable Service
  9. Retrieve Map of Services for a Node
  10. List Services for Node
  11. List Services for Gateway
  12. Methods to Specify Namespace
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)