> ## 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 = () => 
;
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 Pro and Enterprise plans. Every `/api/v1/asset-discovery` endpoint returns status `403 Forbidden` with the `feature_not_available` code and the required tier `cloud` for other plans. If the subscription of a Pro or Enterprise workspace is not active, every endpoint returns status `403 Forbidden` with the `subscription_required` code. 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.
## Plan limits
| Plan | Runs |
| - | - |
| Pro | One free run each UTC calendar day. A run that you start by hand and a scheduled run share the same free run. |
| Enterprise | No limit. Runs do not use credits. |
On Pro, when the free run of the day is used, `POST /api/v1/asset-discovery` returns status `429 Too Many Requests` with the `daily_limit_reached` code. The response has `next_free_run_at`, the UTC time when the next free run opens, and a `Retry-After` header with the same time in seconds. A run that Strix reuses because a run is already in progress does not use the free run. A run that fails before it starts gives the free run back.
The list response has `run_policy`, which is `daily_allowance` on Pro and `credits` on Enterprise, and `next_free_run_at`, which is `null` when a free run is open now.
## Start a run
```bash theme={null}
curl -X POST "https://app.strix.ai/api/v1/asset-discovery" \
-H "Authorization: Bearer " \
-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 "
```
**Required scope:** `discovery:read`
The response contains the most recent runs, the run in progress, the verified domains a run can start from, the schedule, and the run policy of the plan (see [Plan limits](#plan-limits)).
## Get a run
```bash theme={null}
curl -X GET "https://app.strix.ai/api/v1/asset-discovery/runs/" \
-H "Authorization: Bearer "
```
**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 "
```
**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//import" \
-H "Authorization: Bearer " \
-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/" \
-H "Authorization: Bearer " \
-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 " \
-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. On Enterprise, a schedule must fire at most once an hour. On Pro, a schedule must fire at most once a day, because each scheduled run uses the free run of its day. When another run already used the free run of that day, Strix skips the scheduled run and the schedule stays on. If your plan changes to Pro after you saved a schedule that fires more often than once a day, Strix stops the schedule at its next fire and records the code `schedule_too_frequent`. Until you send a new `cron`, an update that omits `cron` returns status 422 with the same code. 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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.