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

# Discovery Utilities Guide

> Helper endpoints for discovery, autocomplete, and safer search UX

## Overview

Discovery utilities help users build safer searches before spending lookups on a
large query. They are most useful when the user does not know the exact breach
source name, supported field, or common value spelling.

The current helper surface is centered around V2 breach autocomplete. These
helpers return raw JSON, not the standard `{success, data}` envelope.

## Value Autocomplete

Value autocomplete suggests likely values across supported breach fields. Use it
for typeahead, field-specific suggestions, and "did you mean" UI before running
a search.

```bash theme={null}
curl -G "https://oathnet.org/api/service/v2/breach/autocomplete" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "q=adob" \
  --data-urlencode "field=dbname"
```

```json theme={null}
{
  "items": [
    {
      "field": "dbname",
      "value": "adobe_2013",
      "count": 152437981
    }
  ],
  "took_ms": 2
}
```

## DB Name Discovery

DB name discovery helps users choose the right source filter. It returns source
suggestions plus the fields available in each source, which is useful before
building strict filters or scanner `query_config`.

```bash theme={null}
curl -G "https://oathnet.org/api/service/v2/breach/autocomplete/dbnames" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "q=link"
```

```json theme={null}
{
  "items": [
    {
      "name": "linkedin_2012",
      "count": 164611595,
      "fields": ["email", "password", "password_hash", "username"]
    }
  ],
  "took_ms": 1
}
```

## Field Coverage

Field coverage answers the inverse question: "which sources contain this field?"
Use it when a workflow needs a field such as `password_hash`, `phone`, or
`username`, but the user does not know which db names are relevant.

```bash theme={null}
curl -G "https://oathnet.org/api/service/v2/breach/autocomplete/fields" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "field=password_hash"
```

```json theme={null}
{
  "field": "password_hash",
  "items": [
    {
      "dbname": "linkedin_2012",
      "count": 164611595
    }
  ],
  "total": 1,
  "took_ms": 1
}
```

## Original Helper

`GET /service/dbname-autocomplete` returns a plain string array. Prefer the V2 db-name autocomplete endpoint for new work because it includes counts and field coverage.

<CardGroup cols={2}>
  <Card title="Breach Search" icon="search" href="/guides/breach-search">
    Use discovered fields and db names in actual searches
  </Card>

  <Card title="Structured Filters" icon="filter" href="/guides/structured-filters">
    Turn discovered values into reusable filter logic
  </Card>

  <Card title="Scanners" icon="radar" href="/guides/scanners">
    Use stable discovered filters for recurring monitoring
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Use OpenAPI for exact parameters, schemas, and playground requests
  </Card>
</CardGroup>