Quickstart - Infrawatch

Infrawatch revisits the internet every day and keeps every observation connected. This page takes you from nothing to a saved investigation and a working API call.

Look something up

Start in the platform. No setup, no API key.

Build an integration

Create a key and make a request.

Watch your own surface

Inventory what you own and work the findings.

Search the internet

Open the platform

Ask in plain language

Type what you are looking for, such as Find me all Fortinet devices, and Infrawatch turns it into a query. You do not need to know the syntax yet.

Read the result

Every result is an observation with a date attached. Open a host to see its services, DNS history, fingerprints, tags, and any reporting that mentions it.

Follow the evidence

Choose Investigate on a host to hand it to InfrAI. It pivots across passive DNS, services, and host inventory at once, then builds a graph you can replay and keep in a project.

Write the query yourself

Once you know what you are looking for, InfraQL is faster than describing it. The basic clause is field:value, and clauses combine with AND, OR, and NOT:

protocol:ssh AND port:22 AND country_code:GB

Use same_service(...) when several conditions must hold on the same service rather than anywhere on the host:

same_service(protocol:https AND http.title="Grafana")

Learn InfraQL

Operators, time windows, correlation, and pattern matching.

Make your first API request

Create an API key

Open API access, create a key with the search.view scope, and copy its secret.

Store the secret when it is shown. Treat it like a password and never place it in browser code or a public repository.

Store it

export INFRAWATCH_API_KEY="<your-api-key>"

Every public endpoint lives under https://api.infrawatch.com/api/v1 and authenticates with the X-API-Key header.

Search for a host

curl --get "https://api.infrawatch.com/api/v1/search/hosts" \
  --header "X-API-Key: ${INFRAWATCH_API_KEY}" \
  --data-urlencode "q=ip:1.1.1.1" \
  --data "limit=1"

import os
import requests

response = requests.get(
    "https://api.infrawatch.com/api/v1/search/hosts",
    headers={"X-API-Key": os.environ["INFRAWATCH_API_KEY"]},
    params={"q": "ip:1.1.1.1", "limit": 1},
    timeout=10,
)
response.raise_for_status()
print(response.json())

const url = new URL(
  "https://api.infrawatch.com/api/v1/search/hosts",
);
url.searchParams.set("q", "ip:1.1.1.1");
url.searchParams.set("limit", "1");

const response = await fetch(url, {
  headers: {
    "X-API-Key": process.env.INFRAWATCH_API_KEY,
  },
});

if (!response.ok) {
  throw new Error(`Infrawatch request failed: ${response.status}`);
}

console.log(await response.json());

Read the response

A host response contains a hosts array and a pagination object:

{
  "query": "ip:1.1.1.1",
  "hosts": [
    {
      "ip_address": "1.1.1.1",
      "asn": 13335,
      "country_code": "US",
      "service_count": 2,
      "ports": [80, 443],
      "protocols": ["http", "https"],
      "transports": ["tcp"],
      "tags": [],
      "services": [],
      "services_truncated": false
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 0,
    "total": 1,
    "total_relation": "eq",
    "has_more": false
  }
}

The exact observation changes over time. Build against the documented shape rather than the example values.

Choose your next query

Question	Dataset	Example query
What is exposed on an IP?	`hosts`	`ip:1.1.1.1`
Which SSH services are visible?	`services`	`protocol:ssh AND port:22`
Which names pointed to an IP?	`dns`	`answer_ip:1.1.1.1`
Which reports mention an IP?	`osint`	`ip:1.1.1.1`

Before you go to production

Validate generated or user-supplied InfraQL with POST /search/{dataset}/validate before scheduling it.
Ignore unknown response fields so backward-compatible additions do not break your client.
Set a request timeout and propagate cancellation.
Honor 429 and 503 responses with bounded backoff.
Log the error request_id; support can use it to trace the request.

Follow an IP investigation

Build host context, inspect services, pivot through DNS, and find reporting.

Browse the field reference

Every searchable field, its type, and the operators it accepts.

Look something up

Build an integration

Watch your own surface

​Search the internet

​Write the query yourself

Learn InfraQL

​Make your first API request

​Choose your next query

​Before you go to production

Follow an IP investigation

Browse the field reference

Search the internet

Write the query yourself

Make your first API request

Choose your next query

Before you go to production