Endpoints
SearchIn REST endpoints on apiv1.osintverse.com.
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 · ReDoc · 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.
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.