> ## 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.

# Quickstart

> Run your first search, investigate a result, and make your first API request

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.

<CardGroup cols={3}>
  <Card title="Look something up" icon="magnifying-glass" href="#search-the-internet">
    Start in the platform. No setup, no API key.
  </Card>

  <Card title="Build an integration" icon="https://mintcdn.com/infrawatch/gCEz_Bv1hOrMPG8n/images/products/api.svg?fit=max&auto=format&n=gCEz_Bv1hOrMPG8n&q=85&s=50b239ba7ccf3ebb74f6b239980bc623" href="#make-your-first-api-request" width="32" height="32" data-path="images/products/api.svg">
    Create a key and make a request.
  </Card>

  <Card title="Watch your own surface" icon="radar" href="/external-surface/overview">
    Inventory what you own and work the findings.
  </Card>
</CardGroup>

## Search the internet

<Steps>
  <Step title="Open the platform">
    Sign in at [app.infrawatch.com](https://app.infrawatch.com). The dashboard
    opens on a search box.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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`:

```text theme={null}
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:

```text theme={null}
same_service(protocol:https AND http.title="Grafana")
```

<Card title="Learn InfraQL" icon="magnifying-glass" href="/search" horizontal>
  Operators, time windows, correlation, and pattern matching.
</Card>

## Make your first API request

<Steps>
  <Step title="Create an API key">
    Open [API access](https://app.infrawatch.com/accounts/api-access), create a
    key with the `search.view` scope, and copy its secret.

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

  <Step title="Store it">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Search for a host">
    <CodeGroup>
      ```bash cURL theme={null}
      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"
      ```

      ```python Python theme={null}
      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())
      ```

      ```javascript JavaScript theme={null}
      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());
      ```
    </CodeGroup>
  </Step>

  <Step title="Read the response">
    A host response contains a `hosts` array and a `pagination` object:

    ```json theme={null}
    {
      "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.
  </Step>
</Steps>

## 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.

<CardGroup cols={2}>
  <Card title="Follow an IP investigation" icon="location-crosshairs" href="/use-cases/investigate-an-ip" arrow>
    Build host context, inspect services, pivot through DNS, and find reporting.
  </Card>

  <Card title="Browse the field reference" icon="database" href="/data-dictionary" arrow>
    Every searchable field, its type, and the operators it accepts.
  </Card>
</CardGroup>