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

# Your first query

> Send an Attack Surface Query to the OASM API, read the response, and check a query before running it

The ASQ endpoints live under `/api/attack-surface`. They use the same authentication as the console: a signed-in session, and the workspace in the `X-Workspace-Id` header.

> [!NOTE]
>
> To query a workspace from an external tool with the workspace API key, use the [MCP server](https://docs.oasm.io/settings/mcp.md): its `query_attack_surface` tool takes the same JSON. See [AI agent and MCP](https://docs.oasm.io/attack-surface-query/ai-agent-and-mcp.md).

## Endpoints

| Method and path | Purpose |
| - | - |
| `GET /api/attack-surface/schema` | The resources, fields, operators and relations you may query |
| `POST /api/attack-surface/query` | Run a batch (or queue it in report mode) |
| `POST /api/attack-surface/explain` | Validate a batch and return its cost, without running it |
| `GET /api/attack-surface/jobs/:jobId` | State and result of a report-mode batch |
| `/api/attack-surface/saved-queries` | Saved queries — see [Saved queries and reports](https://docs.oasm.io/attack-surface-query/saved-queries-and-reports.md) |

## Run a query

**1. Write the batch**

This batch lists the targets of the workspace and counts the hosts under each one.

```json theme={null}
{
  "queries": {
    "targets": { "from": "targets", "select": ["value", "type", "firstSeen"], "limit": 200 },
    "hostsPerTarget": {
      "from": "hosts",
      "groupBy": ["target.value"],
      "aggregate": { "hosts": { "fn": "count" } },
      "orderBy": [{ "field": "hosts", "dir": "desc" }]
    }
  }
}
```

**2. Send it**

The session cookie is the one the console sets when you sign in (named `session`, or `__Secure-session` when OASM is served over HTTPS).

```bash curl theme={null}
curl -X POST "$OASM_URL/api/attack-surface/query" \
  -H "Content-Type: application/json" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Cookie: session=$SESSION" \
  -d @batch.json
```

```javascript fetch (from the console origin) theme={null}
const res = await fetch('/api/attack-surface/query', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json', 'X-Workspace-Id': workspaceId },
  body: JSON.stringify(batch),
});
const { data, meta } = await res.json();
```

**3. Read the response**

Each query comes back under its name in `data`. `meta` carries the time the batch was evaluated at and per-query statistics.

```json theme={null}
{
  "data": {
    "targets": {
      "rows": [
        { "id": "82ec4412-…", "value": "example.com", "type": "DOMAIN", "firstSeen": "2026-11-02T08:14:03.120Z" },
        { "id": "5b591b68-…", "value": "203.0.113.64/28", "type": "CIDR", "firstSeen": "2026-10-28T10:01:44.002Z" }
      ],
      "nextCursor": null,
      "truncated": false
    },
    "hostsPerTarget": {
      "rows": [
        { "target": { "value": "example.com" }, "hosts": 43 },
        { "target": { "value": "203.0.113.64/28" }, "hosts": 16 }
      ],
      "truncated": false
    }
  },
  "meta": {
    "now": "2026-11-18T09:30:00.000Z",
    "tookMs": 18,
    "queries": {
      "targets": { "tookMs": 6, "sqlCount": 1, "cost": 360, "rowCount": 2 },
      "hostsPerTarget": { "tookMs": 9, "sqlCount": 1, "cost": 370, "rowCount": 2 }
    }
  }
}
```

## Reading results

* **Every row has an `id`.** Keep it for follow-up queries (`"field": "id", "op": "eq"`) and for other API calls.
* **Related rows are nested.** `select: ["host.value"]` returns `{ "host": { "value": "…" } }`. A related row that does not exist (a service with no HTTP response) is `null`.
* **Times are ISO 8601 in UTC.**
* **`nextCursor`** is set when more rows exist; send the same query again with `"cursor"` to get the next page. See [Paging, limits and cost](https://docs.oasm.io/attack-surface-query/paging-and-limits.md).
* **`truncated: true`** means a long string was cut or the response size limit was reached.
* **A failed query** comes back as `{ "error": { "code", "message" } }` under its name while the others still return rows. A batch that is invalid as a whole is refused with HTTP 400 — see [Errors](https://docs.oasm.io/attack-surface-query/errors.md).

## Check a query before running it

`POST /api/attack-surface/explain` takes the same body. It validates the batch and returns, per query, the static cost and the database planner's estimate, with hints when a query is too broad:

```json theme={null}
{
  "queries": {
    "targets": {
      "cost": 360,
      "budget": 1000,
      "hints": ["add a window (e.g. \"window\": { \"since\": \"now-7d\" })", "lower limit"],
      "resources": ["targets"],
      "planner": { "totalCost": 12.4, "sortRows": 0 }
    }
  }
}
```

The cost is a heuristic computed before the database is touched; `budget` is the most a query may cost for you. Hints are suggestions, not errors: this query is well within its budget. See [Paging, limits and cost](https://docs.oasm.io/attack-surface-query/paging-and-limits.md).

## Discover the schema

`GET /api/attack-surface/schema` returns the resources you may read, with each field's type, operators, enum values and whether it can be sorted or grouped, and the relations of each resource. The [Resources and fields](https://docs.oasm.io/attack-surface-query/resources.md) page is the same information in readable form.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.