Domains

Use this page as a quick reference for valid search types and options used by POST /search.

Supported search types

Type value	Typical input
`Pseudonym`	`john_doe`
`Email Address`	`[email protected]`
`Domain Name`	`example.com`
`Cryptocurrency`	Wallet address
`IP Address`	`8.8.8.8` or IPv6

These values must match the OpenAPI enum exactly.

Request shape

{
  "query": {
    "type": "Email Address",
    "value": "[email protected]"
  },
  "features": {
    "breached_accounts": true,
    "registered_accounts": "include"
  },
  "cache": {
    "mode": "prefer"
  },
  "delivery": {
    "webhook": {
      "url": "https://client.example/webhooks/osintly",
      "secret": "super-secret-webhook-key"
    }
  }
}

Request sections

Field	Type	Notes
`query`	`object`	Required. Contains `type` and `value`.
`modules`	`object`	Optional. Use `mode: "selected"` plus `ids` to restrict execution.
`leaks`	`object`	Optional. Use `mode: "selected"` plus `sources` to restrict leak providers.
`features`	`object`	Optional. Controls `breached_accounts` and `registered_accounts`.
`cache`	`object`	Optional. Use `mode: "bypass"` to force a fresh execution.
`delivery`	`object`	Optional. Configure `delivery.webhook`.

Module selection behavior (`modules`)

Use modules when you want to restrict execution to a known set of modules.

{
  "query": {
    "type": "Email Address",
    "value": "[email protected]"
  },
  "modules": {
    "mode": "selected",
    "ids": [
      "4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f",
      "95c36c17-f76e-4911-bd4e-8ea57515b2fb"
    ]
  }
}

Server-side validation rules:

Every module ID must exist
Every module ID must be listed and currently available
Every module ID must be compatible with the selected query.type

Default behavior:

If options.modules is omitted or empty, Osintly runs the default module set for that search type
If modules is omitted, Osintly runs the default module set for that search type
If modules.mode is selected, execution is limited to modules.ids

If validation fails, the API returns 400 with an explicit validation error.

ID and pagination parameters

id (path): search UUID
source (path): leak provider source code/name
page (query): leak source page number, minimum 1

Common errors

400 Validation error

Request shape or field values are invalid. Check enum values and data types.

401 Unauthorized

Missing or invalid bearer token.

429 Rate limit exceeded

Respect retry headers and retry after the reset window.

503 Dispatch unavailable

Search creation failed at dispatch layer. Retry with backoff.

API Overview

Endpoints

Supported search types

Request shape

Request sections

Module selection behavior (`modules`)

Common errors

​Supported search types

​Request shape

​Request sections

​Module selection behavior (modules)

​ID and pagination parameters

​Common errors

Supported search types

Request shape

Request sections

Module selection behavior (`modules`)

ID and pagination parameters

Common errors