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

# endpoints

This page gives you a practical map of which endpoint families exist, what they’re used for, and how they fit together in a real integration.

## Recommended integration flow

Most customer integrations follow this pattern:

<Steps>
  <Step title="Define scope">
    Use watchlists to define scope (domains, keywords, BINs, executives, assets).
  </Step>

  <Step title="Query intelligence">
    Query Dataleaks, Exposure, and Ransomware datasets with scoped inputs.
  </Step>

  <Step title="Ingest incrementally">
    Ingest incrementally using pagination and date windows where supported.
  </Step>

  <Step title="Normalize and correlate">
    Normalize and correlate results into downstream systems such as SIEM, SOAR, a data lake, or case management.
  </Step>
</Steps>

## Response envelope

Successful responses use a consistent top-level envelope:

```json title="Single resource" theme={null}
{
  "data": { "...": "..." }
}
```

```json title="List endpoints" theme={null}
{
  "data": [{ "...": "..." }],
  "paging": { "...": "..." }
}
```

```json title="Batch delete" theme={null}
{
  "data": { "count": 3 }
}
```

## Health

Use this for basic connectivity checks (no auth required):

```bash title="Health request" theme={null}
curl -sS "https://api.defendis.ai/health"
```

## Watchlists

Watchlists are the foundation of authorization scope.

<Tabs>
  <Tab title="Groups">
    * `GET /api/v1/watchlists`
    * `POST /api/v1/watchlists/create`
    * `PUT /api/v1/watchlists/{id}`
    * `POST /api/v1/watchlists/delete`
    * `GET /api/v1/watchlists/stats`
  </Tab>

  <Tab title="Assets">
    * `GET /api/v1/watchlists/assets`
    * `POST /api/v1/watchlists/assets`
    * `PUT /api/v1/watchlists/assets/{id}`
    * `POST /api/v1/watchlists/assets/delete`
  </Tab>

  <Tab title="Domains">
    * `GET /api/v1/watchlists/domain`
    * `POST /api/v1/watchlists/domain`
    * `PUT /api/v1/watchlists/domain/{id}`
    * `POST /api/v1/watchlists/domain/delete`
  </Tab>

  <Tab title="BINs">
    * `GET /api/v1/watchlists/bin`
    * `POST /api/v1/watchlists/bin`
    * `PUT /api/v1/watchlists/bin/{id}`
    * `POST /api/v1/watchlists/bin/delete`
  </Tab>

  <Tab title="Executives">
    * `GET /api/v1/watchlists/executive`
    * `POST /api/v1/watchlists/executive`
    * `PUT /api/v1/watchlists/executive/{id}`
    * `POST /api/v1/watchlists/executive/delete`
  </Tab>

  <Tab title="Keywords">
    * `GET /api/v1/watchlists/keyword`
    * `POST /api/v1/watchlists/keyword`
    * `PUT /api/v1/watchlists/keyword/{id}`
    * `POST /api/v1/watchlists/keyword/delete`
  </Tab>

  <Tab title="Ransom groups">
    * `GET /api/v1/watchlists/ransom`
    * `POST /api/v1/watchlists/ransom`
    * `PUT /api/v1/watchlists/ransom/{id}`
    * `POST /api/v1/watchlists/ransom/delete`
  </Tab>
</Tabs>

<Info>
  Many list endpoints accept an optional `watchlistid` query parameter, and batch-delete endpoints use a JSON request body with an `ids` array.
</Info>

<Warning>
  `POST /api/v1/watchlists/domain`, `POST /api/v1/watchlists/keyword`, and `POST /api/v1/watchlists/bin` can return:

  * `403 Forbidden` when enterprise billing access is denied.
  * `409 Conflict` when the corresponding workspace quota is reached (`quota_domains_reached`, `quota_keywords_reached`, `quota_bins_reached`).
</Warning>

## Modules

<Tabs>
  <Tab title="Data leaks">
    * `GET /api/v1/dataleaks/credentials` // requires `domain`
    * `GET /api/v1/dataleaks/credentials/email` // requires `email`
    * `GET /api/v1/dataleaks/documents` // requires `domain`
    * `GET /api/v1/dataleaks/paymentcards/bins` // requires `bin`
    * `GET /api/v1/dataleaks/stats` // requires `domain`
    * `GET /api/v1/dataleaks/user` // requires `id`
  </Tab>

  <Tab title="Exposure">
    * `GET /api/v1/exposure/cves`
    * `GET /api/v1/exposure/subdomains`
    * `GET /api/v1/exposure/hosts` // requires `domainId`
    * `GET /api/v1/exposure/ports`
    * `GET /api/v1/exposure/vulnerabilities`

    <Info>
      Start with `subdomains` and `hosts` to build inventory, then use `ports` and `vulnerabilities` for risk triage and reporting.
    </Info>
  </Tab>

  <Tab title="Ransomware">
    * `POST /api/v1/ransom/stats` // overview stats and trends
    * `GET /api/v1/ransom/groups` // actor and group listing
    * `GET /api/v1/ransom/groups/{id}` // group details
    * `GET /api/v1/ransom/victims` // victim activity listing
    * `GET /api/v1/ransom/country/victims` // victim activity by country
  </Tab>
</Tabs>