> For the complete documentation index, see [llms.txt](https://docs.halosecurity.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.halosecurity.com/api/endpoints/discovery.md).

# Discovery

## Get a count of discovered assets.

<mark style="color:blue;">`GET`</mark> `https://api.halosecurity.com/api/v1/discovery/host-summary.json`

Returns a count of discovered assets.

<https://app.halosecurity.com/user/security/discovery/>

#### Query Parameters

| Name       | Type    | Description                                                                                                                           |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| fqdn       | String  | Search the host or IP field.                                                                                                          |
| scanned    | String  | <p><code>"all"</code> <em>(default)</em><br><code>"yes"</code><br><code>"no"</code><br><code>"ack"</code></p>                         |
| source     | String  | <p><code>"all"</code> <em>(default)</em><br><code>"domain"</code><br><code>"integration"</code><br><code>"network"</code></p>         |
| source\_id | Integer | ID of the object whose type is specified by the `source` field. For example, if `source` is `"domain"`, this is the ID of the domain. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "total": 121
}
```

{% endtab %}
{% endtabs %}

## Get list of discovered assets.

<mark style="color:blue;">`GET`</mark> `https://api.halosecurity.com/api/v1/discovery/host-list.json`

Returns a paginated list of discovered assets.

<https://app.halosecurity.com/user/security/discovery/>

#### Query Parameters

{% hint style="info" %}
The parameters in [host-summary](#query-parameters) are available, along with the following additional parameters:
{% endhint %}

| Name       | Type    | Description                                                              |
| ---------- | ------- | ------------------------------------------------------------------------ |
| sort       | Integer | `0` = FQDN (default)                                                     |
| sort\_desc | Integer | <p><code>0</code> = No <em>(default)</em></p><p><code>1</code> = Yes</p> |
| hostinfo   | Integer | <p><code>0</code> = No <em>(default)</em></p><p><code>1</code> = Yes</p> |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "request": {
        "target_count": 1,
        "sort": "1"
    },
    "pagination": {
        "next": 100,
        "total": 0,
        "start": 0,
        "limit": 100
    },
    "list": [
        {
            "fqdn": "www.example.com",
            "hostinfo": {
                "geo": "US-WA",
                "http_code": 200,
                "ip": "0.0.0.0",
                "favicon_hash": "0",
                "pop_rank": 1,
                "http_location": "https://www.example.com/",
                "tags": [
                    "one",
                    "two"
                ]
            },
            "target": {
                "ip": "0.0.0.0",
                "name": "example",
                "host": "www.example.com",
                "id": 1,
                "scan_id": "0"
            }
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Get list of domains set for discovery.

<mark style="color:blue;">`GET`</mark> `https://api.halosecurity.com/api/v1/discovery/domain-list.json`

Returns a paginated list of domains.

<https://app.halosecurity.com/user/security/discovery/domains/>

#### Query Parameters

| Name       | Type    | Description                                                              |
| ---------- | ------- | ------------------------------------------------------------------------ |
| sort       | Integer | `0` = Domain *(default)*                                                 |
| sort\_desc | Integer | <p><code>0</code> = No <em>(default)</em></p><p><code>1</code> = Yes</p> |
| domain     | String  | Filter by domain, e.g. `"example.com"`                                   |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "list": [
        {
            "domain": {
                "domain_id": 1,
                "domain": "example.com"
            }
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Get list of discovered hostnames.

<mark style="color:blue;">`GET`</mark> `https://api.halosecurity.com/api/v1/discovery/domain-host-list.json`

Returns a paginated list of discovered hostnames.

<https://app.halosecurity.com/user/security/discovery/?source=domain>

#### Query Parameters

| Name       | Type    | Description                                                              |
| ---------- | ------- | ------------------------------------------------------------------------ |
| sort       | Integer | `0` = Domain *(default)*                                                 |
| sort\_desc | Integer | <p><code>0</code> = No <em>(default)</em></p><p><code>1</code> = Yes</p> |
| domain     | String  | Filter by domain                                                         |
| host       | String  | Filter by subdomain                                                      |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "list": [
        {
            "domain": {
                "domain_id": 1,
                "domain": "example.com"
            },
            "host": {
                "domain_id": 1,
                "fqdn": "www.example.com",
                "ip": "0.0.0.0",
                "host": "www",
                "target_id": "1"
            }
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Get list of discovered tlds.

<mark style="color:blue;">`GET`</mark> `https://api.halosecurity.com/api/v1/discovery/domain-tld-list.json`

Returns a paginated list of discovered tlds.

<https://app.halosecurity.com/user/security/discovery/>

#### Query Parameters

| Name       | Type    | Description                                                              |
| ---------- | ------- | ------------------------------------------------------------------------ |
| sort       | Integer | `0` = Domain (default)                                                   |
| sort\_desc | Integer | <p><code>0</code> = No <em>(default)</em></p><p><code>1</code> = Yes</p> |
| domain     | String  | Filter by domain                                                         |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "list": [
        {
            "domain": {
                "domain_id": 1,
                "domain": "example.com"
            },
            "tld": {
                "domain_id": 1,
                "fqdn": "example.ph",
                "ip": "0.0.0.0",
                "tld": "ph"
            }
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Get list of networks set for discovery.

<mark style="color:blue;">`GET`</mark> `https://api.halosecurity.com/api/v1/discovery/network-list.json`

Returns a paginated list of networks.

[https://app.halosecurity.com/user/security/discovery/networks/](https://app.halosecurity.com/user/security/discovery/networks/?)

#### Query Parameters

| Name       | Type    | Description                                                              |
| ---------- | ------- | ------------------------------------------------------------------------ |
| sort       | Integer | `0` = Network *(default)*                                                |
| sort\_desc | Integer | <p><code>0</code> = No <em>(default)</em></p><p><code>1</code> = Yes</p> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "list": [
        {
            "network": {
                "network_id": 1,
                "network_name": "example",
                "network": "0.0.0.0/24"
            }
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Get list of discovered network ips.

<mark style="color:blue;">`GET`</mark> `https://api.halosecurity.com/api/v1/discovery/network-ip-list.json`

Returns a paginated list of discovered network ips.

<https://app.halosecurity.com/user/security/discovery/networks/ips>

#### Query Parameters

| Name       | Type    | Description                                                              |
| ---------- | ------- | ------------------------------------------------------------------------ |
| sort       | Integer | `0` = IP *(default)*                                                     |
| sort\_desc | Integer | <p><code>0</code> = No <em>(default)</em></p><p><code>1</code> = Yes</p> |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "list": [
        {
            "ip": "0.0.0.0",
            "network": {
                "network_id": 1,
                "network_name": "example",
                "network": "0.0.0.0/24"
            }
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Get list of network ports.

<mark style="color:blue;">`GET`</mark> `https://api.halosecurity.com/api/v1/discovery/network-port-list.json`

Returns a paginated list of discovered network ports.

<https://app.halosecurity.com/user/security/discovery/networks/ports>

#### Query Parameters

| Name       | Type    | Description                                                              |
| ---------- | ------- | ------------------------------------------------------------------------ |
| sort       | Integer | `0` = IP *(default)*                                                     |
| sort\_desc | Integer | <p><code>0</code> = No <em>(default)</em></p><p><code>1</code> = Yes</p> |
| protocol   | String  | Filter by protocol                                                       |
| port       | Integer | Filter by port                                                           |
| ip         | String  | Filter by IP                                                             |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "list": [
        {
            "port": {
                "protocol": "tcp",
                "port": 80,
                "ip": "0.0.0.0"
            },
            "network": {
                "network_id": 1,
                "network_name": "example",
                "network": "0.0.0.0/24"
            }
        }
    ]
}
```

{% endtab %}
{% endtabs %}