<commit_before>---
layout: "docs"
page_title: "Catalog (HTTP)"
sidebar_current: "docs-agent-http-catalog"
description: >
  The Catalog is the endpoint used to register and deregister nodes,
  services, and checks. It also provides query endpoints.
---

# Catalog HTTP Endpoint

The Catalog is the endpoint used to register and deregister nodes,
services, and checks. It also provides query endpoints.

The following endpoints are supported:

* [`/v1/catalog/register`](#catalog_register) : Registers a new node, service, or check
* [`/v1/catalog/deregister`](#catalog_deregister) : Deregisters a node, service, or check
* [`/v1/catalog/datacenters`](#catalog_datacenters) : Lists known datacenters
* [`/v1/catalog/nodes`](#catalog_nodes) : Lists nodes in a given DC
* [`/v1/catalog/services`](#catalog_services) : Lists services in a given DC
* [`/v1/catalog/service/<service>`](#catalog_service) : Lists the nodes in a given service
* [`/v1/catalog/node/<node>`](#catalog_nodes) : Lists the services provided by a node

The `nodes` and `services` endpoints support blocking queries and
tunable consistency modes.

### <a name="catalog_register"></a> /v1/catalog/register

The register endpoint is a low-level mechanism for registering or updating
entries in the catalog. Note: it is usually preferrable instead to use the
[agent endpoints](agent.html) for registration as they are simpler and perform anti-entropy.

The register endpoint expects a JSON request body to be PUT. The request
body must look something like:

```javascript
{
  "Datacenter": "dc1",
  "Node": "foobar",
  "Address": "192.168.10.10",
  "Service": {
    "ID": "redis1",
    "Service": "redis",
    "Tags": [
      "master",
      "v1"
    ],
    "Address": "127.0.0.1",
    "Port": 8000
  },
  "Check": {
    "Node": "<PASSWORD>",
    "CheckID": "service:redis1",
    "Name": "<NAME>",
    "Notes": "Script based health check",
    "Status": "passing",
    "ServiceID": "redis1"
  }
}
```

The behavior of the endpoint depends on what keys are provided. The endpoint
requires `Node` and `Address` to be provided while `Datacenter` will be defaulted
to match that of the agent. If only those are provided, the endpoint will register
the node with the catalog.

If the `Service` key is provided, the service will also be registered. 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. The service `Tags`, `Address`,
and `Port` fields are all optional.

If the `Check` key is provided, a health check will also be registered. Note: this
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](agent.html).

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
`unknown`, `passing`, `warning`, or `critical`. The `unknown` status is used
to indicate that the initial check has not been performed yet.

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.

If the API call succeeds, a 200 status code is returned.

### <a name="catalog_deregister"></a> /v1/catalog/deregister

The deregister endpoint is a low-level mechanism for directly removing
entries from the Catalog. Note: it is usually preferrable instead to use the
[agent endpoints](agent.html) for deregistration as they are simpler and perform anti-entropy.

The deregister endpoint expects a JSON request body to be PUT. The request
body must look like one of the following:

```javascript
{
  "Datacenter": "dc1",
  "Node": "foobar",
}
```

```javascript
{
  "Datacenter": "dc1",
  "Node": "foobar",
  "CheckID": "service:redis1"
}
```

```javascript
{
  "Datacenter": "dc1",
  "Node": "foobar",
  "ServiceID": "redis1",
}
```

The behavior of the endpoint depends on what keys are provided. The endpoint
requires `Node` to be provided while `Datacenter` will be defaulted
to match that of the agent. If only `Node` is provided, the node and
all associated services and checks are deleted. If `CheckID` is provided, only
that check is removed. If `ServiceID` is provided, the
service and its associated health check (if any) is removed.

If the API call succeeds a 200 status code is returned.
<commit_msg>Website: finalize cleanup of docs/agent/http/catalog.<commit_after>---
layout: "docs"
page_title: "Catalog (HTTP)"
sidebar_current: "docs-agent-http-catalog"
description: >
  The Catalog is the endpoint used to register and deregister nodes,
  services, and checks. It also provides query endpoints.
---

# Catalog HTTP Endpoint

The Catalog is the endpoint used to register and deregister nodes,
services, and checks. It also provides query endpoints.

The following endpoints are supported:

* [`/v1/catalog/register`](#catalog_register) : Registers a new node, service, or check
* [`/v1/catalog/deregister`](#catalog_deregister) : Deregisters a node, service, or check
* [`/v1/catalog/datacenters`](#catalog_datacenters) : Lists known datacenters
* [`/v1/catalog/nodes`](#catalog_nodes) : Lists nodes in a given DC
* [`/v1/catalog/services`](#catalog_services) : Lists services in a given DC
* [`/v1/catalog/service/<service>`](#catalog_service) : Lists the nodes in a given service
* [`/v1/catalog/node/<node>`](#catalog_nodes) : Lists the services provided by a node

The `nodes` and `services` endpoints support blocking queries and
tunable consistency modes.

### <a name="catalog_register"></a> /v1/catalog/register

The register endpoint is a low-level mechanism for registering or updating
entries in the catalog. Note: it is usually preferrable instead to use the
[agent endpoints](agent.html) for registration as they are simpler and perform anti-entropy.

The register endpoint expects a JSON request body to be PUT. The request
body must look something like:

```javascript
{
  "Datacenter": "dc1",
  "Node": "foobar",
  "Address": "192.168.10.10",
  "Service": {
    "ID": "redis1",
    "Service": "redis",
    "Tags": [
      "master",
      "v1"
    ],
    "Address": "127.0.0.1",
    "Port": 8000
  },
  "Check": {
    "Node": "foobar",
    "CheckID": "service:redis1",
    "Name": "Redis health check",
    "Notes": "Script based health check",
    "Status": "passing",
    "ServiceID": "redis1"
  }
}
```

The behavior of the endpoint depends on what keys are provided. The endpoint
requires `Node` and `Address` to be provided while `Datacenter` will be defaulted
to match that of the agent. If only those are provided, the endpoint will register
the node with the catalog.

If the `Service` key is provided, the service will also be registered. 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. The service `Tags`, `Address`,
and `Port` fields are all optional.

If the `Check` key is provided, a health check will also be registered. Note: this
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](agent.html).

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
`unknown`, `passing`, `warning`, or `critical`. The `unknown` status is used
to indicate that the initial check has not been performed yet.

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.

If the API call succeeds, a 200 status code is returned.

### <a name="catalog_deregister"></a> /v1/catalog/deregister

The deregister endpoint is a low-level mechanism for directly removing
entries from the Catalog. Note: it is usually preferrable instead to use the
[agent endpoints](agent.html) for deregistration as they are simpler and perform anti-entropy.

The deregister endpoint expects a JSON request body to be PUT. The request
body must look like one of the following:

```javascript
{
  "Datacenter": "dc1",
  "Node": "foobar",
}
```

```javascript
{
  "Datacenter": "dc1",
  "Node": "foobar",
  "CheckID": "service:redis1"
}
```

```javascript
{
  "Datacenter": "dc1",
  "Node": "foobar",
  "ServiceID": "redis1",
}
```

The behavior of the endpoint depends on what keys are provided. The endpoint
requires `Node` to be provided while `Datacenter` will be defaulted
to match that of the agent. If only `Node` is provided, the node and
all associated services and checks are deleted. If `CheckID` is provided, only
that check is removed. If `ServiceID` is provided, the
service and its associated health check (if any) are removed.

If the API call succeeds a 200 status code is returned.

{'fraction_non_alphanumeric': 0.10241275758517138, 'fraction_numerical': 0.009319664492078284, 'mean_word_length': 4.3329652125897296, 'pattern_counts': {'":': 48, '<': 17, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7386780', 'n_tokens_mistral': 2897, 'n_tokens_neox': 2749, 'n_words': 1314}