> ## Documentation Index
> Fetch the complete documentation index at: https://docs.app.strix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Asset Discovery

> Find the hosts and infrastructure that belong to your organization, then import them as domains

export const ScarfPixel = () => <img referrerPolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=831669b6-b4bd-42cb-8832-2122c03e1d5f" alt="" width="1" height="1" style={{
  position: "absolute",
  width: 0,
  height: 0,
  opacity: 0,
  pointerEvents: "none"
}} />;

<ScarfPixel />

Asset Discovery runs a passive reconnaissance agent against the domains you verified. The agent finds hosts, certificates, providers, and infrastructure that belong to your organization. The agent does not attack a target. Strix writes each asset to the inventory as soon as the agent finds it.

Asset Discovery is available on the Enterprise plan. Every `/api/v1/asset-discovery` endpoint returns status `403 Forbidden` with the `feature_not_available` code and the required tier `enterprise` for other plans. If Strix cannot verify the plan, every endpoint returns status `503 Service Unavailable` with the `entitlement_unverified` code. Retry the request after the number of seconds in the `Retry-After` header.

## Start a run

```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/asset-discovery" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "seeds": ["example.com"],
    "org_names": ["Example Inc"],
    "instructions": "Include the hosts on our cloud accounts."
  }'
```

**Required scope:** `discovery:write`

All fields are optional. When you omit `seeds`, the run starts from every verified domain. Each entry in `seeds` must be a domain that your organization verified. Strix returns status `422` for an unverified or malformed domain.

Strix runs one discovery per organization at a time. When a run is in progress, the endpoint returns that run with `reused` set to `true`.

## List runs

```bash theme={null}
curl -X GET "https://app.strix.ai/api/v1/asset-discovery" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

**Required scope:** `discovery:read`

The response contains the most recent runs, the run in progress, the verified domains a run can start from, and the schedule.

## Get a run

```bash theme={null}
curl -X GET "https://app.strix.ai/api/v1/asset-discovery/runs/<RUN_ID>" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

**Required scope:** `discovery:read`

A completed run has a `summary`. The summary has at most four short lines. The first line gives the number of hosts. Each other line names one asset that can be a concern and says why. The summary does not describe how the agent found the assets.

## List discovered assets

```bash theme={null}
curl -X GET "https://app.strix.ai/api/v1/asset-discovery/assets?status=new&apex=example.com" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

**Required scope:** `discovery:read`

By default the response contains only assets with the `new` status. Set `status` to `all` to include imported and ignored assets. You can also filter by `search`, `source`, `kind`, `apex`, and `run_id`.

## Import an asset as a domain

```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/asset-discovery/assets/<ASSET_ID>/import" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"asset_type": "web_app"}'
```

**Required scope:** `discovery:write`

When the host is under a domain that your organization verified, Strix marks the new domain as verified. You can start a scan on that domain at once. When the host is not under a verified domain, verify the new domain first. See [Scans](/guides/scans) for domain verification.

## Ignore or restore an asset

```bash theme={null}
curl -X PATCH "https://app.strix.ai/api/v1/asset-discovery/assets/<ASSET_ID>" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"status": "ignored"}'
```

**Required scope:** `discovery:write`

Set `status` to `new` to show the asset again. An imported asset cannot change status.

## Schedule recurring runs

A schedule starts a run at a fixed time from every verified domain. Domains that you verify later are part of the next run.

```bash theme={null}
curl -X PATCH "https://app.strix.ai/api/v1/asset-discovery/schedule" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "cron": "0 9 * * 1",
    "timezone": "America/New_York",
    "notify_events": ["new_assets", "failed"],
    "notify_slack": true,
    "slack_channel_id": "C0123456789",
    "notify_emails": ["security@example.com"]
  }'
```

**Required scope:** `discovery:write`

`cron` is a 5-field cron expression (minute, hour, day of month, month, day of week). Strix reads it in `timezone`, an IANA timezone name. The example runs every Monday at 09:00 in New York, also across daylight saving changes. A schedule must fire at most once every 6 hours. Send `null` as `cron` to stop recurring runs. Fields that you omit keep their current value. `notify_events` and `notify_emails` replace the full list. `notify_emails` accepts up to 10 addresses. Send an empty list to stop email notifications.

To read the schedule, send `GET` to the same path with the `discovery:read` scope. The response includes `next_run_at` as a UTC timestamp, `last_fired_at`, and the status of the last scheduled run.

## Notifications

The notification settings apply to scheduled runs and to runs that you start by hand. `notify_events` selects the outcomes that send a message. A run sends at most one message.

| Event        | When Strix sends a message                                                                                                                 |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `new_assets` | A completed run found assets that were not in the inventory before. This is the default.                                                   |
| `completed`  | A run completed, also when it found nothing new. A completed run with new assets sends one message, as `new_assets` when that event is on. |
| `failed`     | A run stopped without a result.                                                                                                            |

Send an empty `notify_events` list to stop all notifications.

* With `notify_slack` set to `true`, Strix posts to the channel in `slack_channel_id`. The channel must be in the connected Slack workspace. Set `slack_channel_id` to `null` to post to the default channel of the Slack integration. See [Slack integration](/guides/slack-integration).
* Each address in `notify_emails` gets one email. For `new_assets`, the email lists the new hosts and the run summary.

A message never contains a price or a credit amount.