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

# API Reference Overview

> How OathNet API families work, with exact endpoint contracts in OpenAPI

## Base URL

All API requests are made to:

```bash theme={null}
https://oathnet.org/api
```

## Authentication

Most service requests require an API key in the `x-api-key` header:

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" https://oathnet.org/api/service/v2/breach/search?q=test@example.com
```

<Card title="Get Your API Key" icon="key" href="https://oathnet.org/dashboard?tab=account">
  Generate an API key from your dashboard
</Card>

## API Families

* `/service/*`
  Search sessions, original search routes, and OSINT point lookups.
* `/service/v2/*`
  Current search, victims, file search, exports, bulk search, autocomplete, and AI filter endpoints.
* `/scanners/*`
  Automated monitoring and notification management for stealer and breach scanners.

<Note>
  Prefer `/service/v2/*` and `/scanners/*` for new search and monitoring integrations.
</Note>

## OpenAPI Reference

The generated OpenAPI reference is the canonical API contract. Use it for exact
paths, methods, parameters, schemas, enums, content types, auth, and the
interactive playground.

The hand-written docs are guides. They explain product meaning, workflow
choices, response-shape caveats, and examples, while OpenAPI remains the only
endpoint-by-endpoint reference.

<Steps>
  <Step title="Enter Your API Key">
    Click the "Authorization" section in the playground and enter your API key
  </Step>

  <Step title="Set Parameters">
    Fill in the required parameters for the endpoint
  </Step>

  <Step title="Send Request">
    Click "Send" to execute the request and inspect the live response
  </Step>
</Steps>

<Note>
  Your API key is stored locally in your browser and is only sent directly to the API server.
</Note>

## Success Response Patterns

OathNet no longer has one universal success shape. There are three main patterns:

| Pattern                 | Common endpoints                                                                                                                                                                                                                                     | Notes                                                                  |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Envelope JSON**       | Search-session and OSINT endpoints, `v2/stealer/search`, `v2/breach/search`, `v2/victims/search`, `v2/stealer/investigation/search`, `v2/stealer/subdomain`, `v2/bulk-search` create                                                                 | Successful responses include `success`, `message`, and `data`          |
| **Raw JSON**            | `v2/breach/autocomplete*`, `v2/ai/filter*`, `v2/files/search`, `v2/victims/*/properties`, `v2/victims/*/summary`, `v2/victims/*/cookies`, `v2/phonebook`, `v2/file-search*`, `v2/exports*`, `v2/bulk-search` list and status, most scanner endpoints | Successful responses rely on HTTP status and the payload body directly |
| **File or text stream** | Victim file downloads, victim cookie-domain inspection, victim archive downloads, export downloads, bulk-search downloads                                                                                                                            | The body is text or binary, not JSON                                   |

### Envelope Example

```json theme={null}
{
  "success": true,
  "message": "Request completed successfully",
  "data": {
    "items": [],
    "meta": {
      "count": 0,
      "total": 0,
      "took_ms": 4,
      "has_more": false,
      "total_pages": 0
    }
  }
}
```

### Raw JSON Example

```json theme={null}
{
  "job_id": "exp_123",
  "status": "running",
  "created_at": "2026-04-18T12:00:00Z",
  "progress": {
    "records_done": 150,
    "records_total": 1000,
    "bytes_done": 32768,
    "percent": 15,
    "updated_at": "2026-04-18T12:00:05Z"
  }
}
```

## Error Handling

API-generated errors are generally normalized into the standard error envelope, even for endpoints whose successful responses are raw JSON or file streams.

See [Error Handling](/guides/error-handling) for client guidance.

## Structured Filter System

The current search stack has one shared filter grammar across V2 search, AI filter output, exports, bulk search, and scanners.

* use `filter` for explicit JSON filter trees
* use `filter_id` to replay a stored AI or prior-search context
* combine flat filters with structured filters when needed

See [Structured Filters](/guides/structured-filters) for the full grammar, operator matrix, merge order, and scanner/export reuse rules.

## Workflow Guides

Use the guides for product meaning, expected workflows, examples, and
response-style caveats. They are intentionally not the canonical endpoint
reference.

<CardGroup cols={2}>
  <Card title="Search Sessions" icon="arrows-rotate" href="/guides/search-sessions">
    Group related searches and preserve quota context
  </Card>

  <Card title="Breach Search" icon="database" href="/guides/breach-search">
    Search breach records and use autocomplete or AI filters
  </Card>

  <Card title="Stealer Search" icon="search" href="/guides/stealer-search">
    Search stealer credentials, investigation fanout, and phonebook intelligence
  </Card>

  <Card title="Structured Filters" icon="filter" href="/guides/structured-filters">
    Understand filter, filter\_id, query\_config, and merge behavior
  </Card>

  <Card title="Victims" icon="user" href="/guides/victims">
    Search victim summaries, inspect manifests, and retrieve files
  </Card>

  <Card title="File Search" icon="file-search" href="/guides/file-search">
    Run asynchronous searches across victim file contents
  </Card>

  <Card title="Exports" icon="download" href="/guides/exports">
    Create, poll, and download export jobs
  </Card>

  <Card title="Scanners" icon="radar" href="/guides/scanners">
    Monitor newly indexed data and verify webhook deliveries
  </Card>

  <Card title="OSINT Lookups" icon="globe" href="/guides/osint-lookups">
    Use social, gaming, network, and email enrichment helpers
  </Card>

  <Card title="Utilities" icon="wrench" href="/guides/utilities">
    Discover breach sources, fields, and autocomplete values
  </Card>
</CardGroup>

## Quotas & Plans

Lookup billing and feature access vary by endpoint family. Search, file search, exports, bulk search, archive downloads, AI filter creation, and scanner quotas all depend on plan features.

See [Rate Limiting](/guides/rate-limiting) and [Scanners](/guides/scanners) for the current customer-facing behavior.

## OpenAPI Specification

Download our complete OpenAPI 3.1.0 specification:

<Card title="Download OpenAPI Spec" icon="download" href="/openapi.yaml">
  Get the full API specification in YAML format
</Card>