> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infrawatch.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API overview
> Build investigations and security workflows with the Infrawatch public API
The Infrawatch API is a JSON REST API for infrastructure search, enrichment,
external-surface workflows, browser evidence, rules, and intelligence reports.
## Base URL
```text theme={null}
https://api.infrawatch.com/api/v1
```
Endpoint pages show paths relative to this URL.
## Authenticate
Create and manage API keys in
[API access](https://app.infrawatch.com/accounts/api-access), then send the key
in `X-API-Key`:
```bash cURL theme={null}
curl --get "https://api.infrawatch.com/api/v1/search/hosts" \
--header "X-API-Key: " \
--data-urlencode "q=ip:1.1.1.1" \
--data "limit=1"
```
```python Python theme={null}
import requests
response = requests.get(
"https://api.infrawatch.com/api/v1/search/hosts",
headers={"X-API-Key": ""},
params={"q": "ip:1.1.1.1", "limit": 1},
timeout=10,
)
response.raise_for_status()
print(response.json())
```
```javascript JavaScript theme={null}
const url = new URL(
"https://api.infrawatch.com/api/v1/search/hosts?q=ip%3A1.1.1.1&limit=1",
);
const response = await fetch(url, {
headers: { "X-API-Key": "" },
});
if (!response.ok) {
throw new Error(`Infrawatch request failed: ${response.status}`);
}
console.log(await response.json());
```
Authentication and access are derived from the key. Keep keys in server-side
secret storage and never expose them in client-side code.
Create a key, choose scopes, set the header, and handle authentication
errors.
Create a scoped key, run a host search, and inspect the response.
## Choose an API
Search hosts, services, DNS, and OSINT; discover subdomains; validate
InfraQL; run bulk lookup; count and aggregate results.
Manage project inventory, services, and the lifecycle of externally visible
findings.
Run isolated browser sessions and collect screenshots, network events, and
replay evidence.
Author detection rules, manage tags, and inspect rule observations and
activity.
Retrieve published intelligence reports, facets, and extracted indicators.
## Errors
Errors use a stable JSON envelope:
```json theme={null}
{
"error": {
"code": "invalid_request",
"message": "The request is invalid.",
"request_id": "019c4f5f-4b50-7c6f-a759-b0da72a53c69"
}
}
```
* Use `code` for program logic.
* Show `message` to an operator.
* Retain `request_id` for support.
* Back off when the API returns `429` or a retryable `503`.
## Versioning
Public endpoints are versioned in the URL where applicable. Backward-compatible
fields and enum values can be added over time, so clients should ignore values
they do not yet recognize.
Browse public search fields, types, operators, and meanings.
Follow practical IP, service, DNS, bulk-enrichment, and aggregation recipes.