# Endpoints

SearchIn REST endpoints on apiv1.osintverse.com.

URL: https://osintverse.com/docs/api/overview

All paths are relative to `https://apiv1.osintverse.com`.

| Method | Path                     | Auth | Description                                                               |
| ------ | ------------------------ | ---- | ------------------------------------------------------------------------- |
| `GET`  | `/health`                | No   | Service health check.                                                     |
| `GET`  | `/v1/providers`          | No   | Provider catalog with supported input types and pricing.                  |
| `POST` | `/v1/search/quote`       | Yes  | Price a search and check the wallet. Never charges.                       |
| `POST` | `/v1/search`             | Yes  | Create and run an OSINT search.                                           |
| `POST` | `/v1/search/bulk`        | Yes  | Create many searches (`queries[]` × `providers[]`).                       |
| `POST` | `/v1/search/:id/unlock`  | Yes  | Unlock remaining LeakRadar credentials ($0.50 per 1,000).                 |
| `POST` | `/v1/search/:id/premium` | Yes  | Run OSINT Industries premium modules on a completed search ($1.80).       |
| `POST` | `/v1/search/:id/cancel`  | Yes  | Stop a running OSINT Industries search (keeps charge and modules so far). |
| `GET`  | `/v1/search/:id`         | Yes  | Poll search status / get results.                                         |

Interactive docs: [Swagger](https://apiv1.osintverse.com/docs) · [ReDoc](https://apiv1.osintverse.com/redoc) · [OpenAPI JSON](https://osintverse.com/openapi.json) (also at `https://apiv1.osintverse.com/openapi.json`)

## GET /v1/providers

Returns the live catalog. Use it to discover valid `provider` + `input_type` pairs and `price_usd` before you search. Caching this for a few minutes is fine; prices can change.

## POST /v1/search/quote

Prices `count` lookups (default 1, max 100) of one `provider` + `input_type` (+ `premium`) and compares the total with the wallet the key bills. Returns `unit_cost_usd`, `total_cost_usd`, `balance_usd`, `sufficient_balance`, `shortfall_usd`, and a `top_up_url` to hand to a person. Nothing is charged, so agents should quote before every paid call.

```bash title="Quote before you run"
curl -X POST "https://apiv1.osintverse.com/v1/search/quote"   -H "Content-Type: application/json" -H "x-api-key: ov_your_api_key"   -d '{"provider":"leakradar","input_type":"email"}'
```

## POST /v1/search

Creates a billed search. Charge is applied when the search is accepted. Upstream failures after billing set status `refunded` and restore the balance.

| Field        | Type      | Required | Description                                                                                                                                                                        |
| ------------ | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`   | `string`  | Yes      | Provider id from `GET /v1/providers`, for example `leakradar` or `securitytrails`.                                                                                                 |
| `input_type` | `string`  | Yes      | One of `email`, `username`, `phone`, `domain`, `name`, `image`, or `ip` — must be valid for the provider.                                                                          |
| `query`      | `string`  | Yes      | The identifier or URL to search. Image providers accept a public image URL. Hunter.io name searches use `Full Name example.com` (person name, then company domain).                |
| `premium`    | `boolean` | No       | OSINT Industries only. Defaults to **false** — premium modules are excluded. Set true to include Snapchat, TikTok, and similar for an extra **$1.80** (total **$2.40**). |

**Safe retries.** Send an `Idempotency-Key` header (any unique string up to 128 characters) with each new search. If the response is lost and you retry with the same key and body, you get the original search back and are not charged again. The same key with a different body returns **409**.

## POST /v1/search/bulk

Creates up to **100** billed searches in one call: every `queries[]` × `providers[]` pair (max **50** queries). Partial success is expected — check `searches[]` and `summary`. Poll any `running` job with `GET /v1/search/:id`. The call counts once toward the daily key rate limit, however many jobs it starts.

| Field        | Type       | Required | Description                                                                                                                                |
| ------------ | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `input_type` | `string`   | Yes      | Shared input type for every query.                                                                                                         |
| `queries`    | `string[]` | Yes      | Identifiers or image URLs (deduped after validation).                                                                                      |
| `providers`  | `string[]` | Yes      | Provider ids to run for each query.                                                                                                        |
| `premium`    | `boolean`  | No       | Defaults to **false**. When true, OSINT Industries jobs in the batch include premium modules (+$1.80 each). Other providers are unchanged. |

## GET /v1/search/:id

Returns the same search object as create. FaceCheck and OSINT Industries may stay `running` — poll about every 2 seconds. OSINT Industries includes growing `result.matches` while still running. You can only read searches owned by the key's account (**404** otherwise).

## POST /v1/search/:id/unlock

LeakRadar only. Unlocks remaining credential rows on a completed search at **$0.50 per 1,000** (`ceil(remaining / 1000) × 0.50`). Returns the updated search object. Insufficient balance returns **402**. Non-LeakRadar searches return **422**.

## POST /v1/search/:id/premium

OSINT Industries only. Runs premium modules on a **completed** basic search for **$1.80**. Returns the updated search with premium modules merged in. If premium was already run, returns the current search with no charge. Insufficient balance returns **402**. Non-OSINT Industries or incomplete searches return **422**. Upstream failure refunds the extra $1.80 only — the original search stays `completed`.

## POST /v1/search/:id/cancel

OSINT Industries only. Stops an in-flight streamed search. Modules already returned stay on the job and status becomes `completed`. The original charge is kept — this is not a refund. Non-OSINT Industries jobs, or jobs that are not `running`, return **422**. Already terminal jobs are a no-op.