{"openapi":"3.1.0","info":{"title":"OSINTverse API","description":"\nProgrammatic access to **SearchIn** — unified OSINT search across LeakRadar, OSINT Industries, Shodan, Facecheck.id, Picarta.ai, Whoxy, and more.\n\n## Base URL\n\nProduction: `https://apiv1.osintverse.com`\n\n## Authentication\n\nSend your API key in the **`x-api-key`** header on every authenticated request:\n\n```\nx-api-key: ov_your_secret_key\n```\n\nCreate keys at [https://osintverse.com/dashboard/api](https://osintverse.com/dashboard/api).\nKeys use the `ov_` prefix and are shown only once at creation.\n\n**Rate limit:** 1,000 requests per day per API key.\n\n## Billing\n\nSearches deduct a flat USD amount from your account balance before the provider runs\n(see `GET /v1/providers`). **LeakRadar** charges **$1.00** per query and includes\n1,000 credential unlocks. Remaining rows unlock from the same job with\n`POST /v1/search/{id}/unlock` at **$0.50 per 1,000** (`ceil(remaining / 1000) × 0.50`).\n**OSINT Industries** is **$0.60** per query; premium modules are excluded unless you set\n`premium: true` (or call `POST /v1/search/{id}/premium` after a basic search) to include\nSnapchat, TikTok, and other premium modules for an extra **$1.80**.\nIf your balance is insufficient, the search returns `failed` with no charge\n(extra unlocks and premium add-ons return HTTP **402**).\nIf an upstream provider fails after billing (timeout, auth, rate limit, 5xx), the charge is **refunded** (`refunded` status;\nextra unlock and premium failures refund only the extra amount and keep the original search completed).\nClient-rejected inputs that the vendor will not analyze (for example GeoSeer `invalid_request` on portraits / indoor photos)\nstay **charged** with status `failed`.\nA successful lookup that returns no rows stays `completed` and stays charged.\n\n## Async searches\n\nFaceCheck image searches may return `status: running`. Poll `GET /v1/search/{id}` every 2 seconds until\nthe status is `completed`, `failed`, or `refunded`.\n\nCompleted FaceCheck results normalize each match to:\n\n```json\n{ \"score\": 97, \"url\": \"https://example.com/page\", \"thumbnail\": \"data:image/webp;base64,...\" }\n```\n\nSource metadata includes `total_results`, `returned`, `testing_mode`, and `search_id`.\n\n## Full integration guide\n\n[Developer documentation](https://osintverse.com/developers)\n","contact":{"name":"OSINTverse","url":"https://osintverse.com/","email":"hi@osintverse.com"},"license":{"name":"Proprietary","url":"https://osintverse.com/privacy"},"version":"0.1.0"},"paths":{"/health":{"get":{"tags":["health"],"summary":"Health check","description":"Returns service status. Used by Railway health checks and uptime monitoring. No authentication required.","operationId":"health","responses":{"200":{"description":"Service is healthy.","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Health Health Get"}}}}}}},"/v1/providers":{"get":{"tags":["providers"],"summary":"List OSINT providers","description":"Returns all integrated OSINT providers with supported input types and flat per-query USD pricing. LeakRadar includes 1,000 credential unlocks in the query price; leftover rows unlock at $0.50 per 1,000 via POST /v1/search/{id}/unlock. OSINT Industries premium modules add $1.80 via `premium=true` or POST /v1/search/{id}/premium. Use this to discover valid `provider` + `input_type` combinations before calling `POST /v1/search`. No authentication required.","operationId":"list_providers","responses":{"200":{"description":"Provider catalog with pricing.","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ProviderCatalogItem"},"type":"array","title":"Response List Providers V1 Providers Get"}}}},"500":{"description":"Standard error body: `{ \"detail\": \"Human-readable message\" }`. Validation errors may include an additional `errors` array."}}}},"/v1/webhooks/secret":{"get":{"tags":["search","webhooks"],"summary":"Get the webhook signing secret","description":"Secret for verifying `callback_url` events from searches billed to this wallet (the team wallet for team keys). Events follow Standard Webhooks: check `webhook-signature` (`v1,` + base64 HMAC-SHA256 over `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the base64 part after `whsec_`), and reject timestamps older than five minutes. Never charges.","operationId":"get_webhook_secret","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-User-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-User-Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Organization-Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Api-Key-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Id"}},{"name":"X-Api-Key-Daily-Cap-Usd","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Daily-Cap-Usd"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Webhook Secret V1 Webhooks Secret Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/search/quote":{"post":{"tags":["search"],"summary":"Quote a search","description":"Price one or more lookups of a provider + input type and check them against the wallet the API key bills. **Never charges.** Agents should quote before `POST /v1/search` and send the person `top_up_url` when `sufficient_balance` is false.","operationId":"quote_search","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-User-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-User-Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Organization-Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Api-Key-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Id"}},{"name":"X-Api-Key-Daily-Cap-Usd","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Daily-Cap-Usd"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchQuoteRequest"}}}},"responses":{"200":{"description":"Price, current balance, and whether the wallet can pay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchQuoteResponse"}}}},"401":{"description":"Missing or invalid API key."},"422":{"description":"Invalid provider/input_type pair."}},"security":[{"ApiKeyAuth":[]}]}},"/v1/search":{"post":{"tags":["search"],"summary":"Create a search","description":"Run an OSINT search against the specified provider. Requires **`x-api-key`** header authentication.\n\n**Billing:** USD is deducted from your account balance before the upstream query runs. Returns `failed` if balance is insufficient (no charge). Returns `refunded` if the upstream provider fails after billing (timeout, auth, rate limit, or 5xx — not an empty successful lookup).\n\n**Async:** FaceCheck image searches and OSINT Industries lookups may return `status: running` with a `poll_url`. Poll `GET /v1/search/{id}` every ~2 seconds. OSINT Industries `result.matches` grows as modules finish. Stop an in-flight OSINT Industries job with `POST /v1/search/{id}/cancel` (keeps the charge and any modules already returned).\n\n**Retries:** send an `Idempotency-Key` header (any unique string up to 128 characters). A retry with the same key returns the original search and is not charged again; the same key with a different body returns **409**.","operationId":"create_search","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Unique per search. A retry with the same key returns the original search without charging again.","title":"Idempotency-Key"},"description":"Unique per search. A retry with the same key returns the original search without charging again."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-User-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-User-Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Organization-Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Api-Key-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Id"}},{"name":"X-Api-Key-Daily-Cap-Usd","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Daily-Cap-Usd"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchCreateRequest"}}}},"responses":{"200":{"description":"Search created (or replayed for a repeated Idempotency-Key). Check `status` for results or polling.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"409":{"description":"Idempotency-Key already used for a different search."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Account is banned."},"422":{"description":"Invalid provider/input_type pair or query validation failed."},"502":{"description":"API key verification or upstream provider error."},"503":{"description":"API key verification is not configured."}},"security":[{"ApiKeyAuth":[]}]}},"/v1/search/bulk":{"post":{"tags":["search"],"summary":"Create a bulk search","description":"Run many OSINT searches in one request: every `queries[]` × `providers[]` pair (max 50 queries, max 100 jobs). Requires **`x-api-key`** or internal BFF auth.\n\n**Billing:** each job is charged like `POST /v1/search`. Partial success is normal — inspect `searches[]` and `summary`. Insufficient balance fails that job only.\n\n**Free lookups:** at most one gifted lookup is used per provider in the batch.\n\n**Async:** poll `GET /v1/search/{id}` for any job with `status: running`. The call counts once toward the daily API key rate limit, however many jobs it starts.","operationId":"create_search_bulk","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-User-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-User-Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Organization-Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Api-Key-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Id"}},{"name":"X-Api-Key-Daily-Cap-Usd","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Daily-Cap-Usd"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchBulkCreateRequest"}}}},"responses":{"200":{"description":"Batch accepted. Check each job in `searches`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchBulkResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Account is banned."},"422":{"description":"Invalid body, query validation, or job-count limits exceeded."},"502":{"description":"API key verification or upstream provider error."},"503":{"description":"API key verification is not configured."}},"security":[{"ApiKeyAuth":[]}]}},"/v1/search/{search_id}":{"get":{"tags":["search"],"summary":"Get search status","description":"Retrieve a search job by ID. Use this to **poll async searches** (FaceCheck, OSINT Industries) until `status` is `completed`, `failed`, or `refunded`.\n\nOSINT Industries jobs include growing `result.matches` while still `running`.\n\nRequires **`x-api-key`** header. You can only access searches created by your account.","operationId":"get_search","parameters":[{"name":"search_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Search Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-User-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-User-Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Organization-Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Api-Key-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Id"}},{"name":"X-Api-Key-Daily-Cap-Usd","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Daily-Cap-Usd"}}],"responses":{"200":{"description":"Current search status and results (if complete).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Account is banned."},"404":{"description":"Search not found or not owned by this account."},"502":{"description":"Standard error body: `{ \"detail\": \"Human-readable message\" }`. Validation errors may include an additional `errors` array."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/v1/search/{search_id}/cancel":{"post":{"tags":["search"],"summary":"Stop a running OSINT Industries search","description":"OSINT Industries only. Stops an in-flight streamed search, keeps every module already returned, and **does not refund** the lookup. Already settled jobs (`completed`, `refunded`, `failed`) return the current search. Other providers return **422**.","operationId":"cancel_search","parameters":[{"name":"search_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Search Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-User-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-User-Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Organization-Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Api-Key-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Id"}},{"name":"X-Api-Key-Daily-Cap-Usd","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Daily-Cap-Usd"}}],"responses":{"200":{"description":"Search stopped (or already settled). Charge is kept.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Account is banned."},"404":{"description":"Search not found or not owned by this account."},"422":{"description":"Not OSINT Industries, or the job is not running."}},"security":[{"ApiKeyAuth":[]}]}},"/v1/search/{search_id}/unlock":{"post":{"tags":["search"],"summary":"Unlock remaining LeakRadar results","description":"LeakRadar only. Unlocks leftover 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**. If nothing remains, returns the current search with no charge.","operationId":"unlock_search","parameters":[{"name":"search_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Search Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-User-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-User-Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Organization-Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Api-Key-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Id"}},{"name":"X-Api-Key-Daily-Cap-Usd","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Daily-Cap-Usd"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchUnlockRequest"}}}},"responses":{"200":{"description":"Updated search with additional unlocked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"401":{"description":"Missing or invalid API key."},"402":{"description":"Insufficient balance for extra unlocks."},"403":{"description":"Account is banned."},"404":{"description":"Search not found or not owned by this account."},"422":{"description":"Not a LeakRadar search, not completed, or unlock_remaining is false."},"502":{"description":"Upstream LeakRadar error after extra unlock billing (extra charge refunded)."}},"security":[{"ApiKeyAuth":[]}]}},"/v1/search/{search_id}/premium":{"post":{"tags":["search"],"summary":"Run OSINT Industries premium modules","description":"OSINT Industries only. Runs premium modules (Snapchat, TikTok, and similar) on a **completed** basic search for an extra **$1.80**. Returns the updated search with premium modules merged in. Insufficient balance returns **402**. If premium modules were already run, returns the current search with no charge.","operationId":"run_premium_search","parameters":[{"name":"search_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Search Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"X-User-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-User-Id"}},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Organization-Id"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"X-Api-Key-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Id"}},{"name":"X-Api-Key-Daily-Cap-Usd","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key-Daily-Cap-Usd"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPremiumRequest"}}}},"responses":{"200":{"description":"Updated search with premium modules merged in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"401":{"description":"Missing or invalid API key."},"402":{"description":"Insufficient balance for premium modules."},"403":{"description":"Account is banned."},"404":{"description":"Search not found or not owned by this account."},"422":{"description":"Not OSINT Industries, not completed, or premium is false."},"502":{"description":"Upstream OSINT Industries error after premium billing (extra charge refunded)."}},"security":[{"ApiKeyAuth":[]}]}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ProviderCatalogItem":{"properties":{"id":{"type":"string","title":"Id","description":"Provider identifier used in search requests."},"name":{"type":"string","title":"Name","description":"Human-readable provider name."},"category":{"type":"string","title":"Category","description":"Provider category label."},"max_unlocks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Unlocks","description":"LeakRadar: credential unlocks included in the query price. Remaining rows unlock via POST /v1/search/{id}/unlock."},"extra_unlock_usd_per_1k":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extra Unlock Usd Per 1K","description":"LeakRadar: USD charged per additional 1,000 credential unlocks after max_unlocks."},"premium_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Premium Usd","description":"OSINT Industries: extra USD to include premium modules (Snapchat, TikTok, and similar)."},"input_types":{"items":{"additionalProperties":{"type":"string"},"type":"object"},"type":"array","title":"Input Types","description":"Supported input types with per-query USD price (`price_usd`)."}},"type":"object","required":["id","name","category","input_types"],"title":"ProviderCatalogItem","description":"OSINT provider with supported input types and pricing.","examples":[{"category":"Breach intelligence","extra_unlock_usd_per_1k":"0.50","id":"leakradar","input_types":[{"id":"email","price_usd":"1.00"},{"id":"username","price_usd":"1.00"},{"id":"domain","price_usd":"1.00"}],"max_unlocks":1000,"name":"LeakRadar"}]},"ProviderResultPayload":{"properties":{"sources":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Sources","description":"High-level source metadata from the provider response."},"matches":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Matches","description":"Individual match records to display or process."},"raw":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"null"}],"title":"Raw","description":"Unmodified upstream provider payload."}},"type":"object","title":"ProviderResultPayload","description":"Normalized search results from the upstream OSINT provider."},"SearchBulkCreateRequest":{"properties":{"input_type":{"type":"string","enum":["email","username","phone","domain","name","image","ip","crypto"],"title":"Input Type","description":"Shared input type for every query in the batch."},"queries":{"items":{"type":"string"},"type":"array","maxItems":50,"minItems":1,"title":"Queries","description":"Search values (max 50). Normalized and deduped after validation."},"providers":{"items":{"type":"string","enum":["osint-industries","leakradar","leakosintbot","facecheck","picarta","geoseeer","predicta-search","dehashed","whoxy","whoisxml","securitytrails","snusbase","shodan","hunter","builtwith","blockchair","ipqs"]},"type":"array","minItems":1,"title":"Providers","description":"Providers to run for each query. Cartesian product with queries must be ≤ 100."},"created_via":{"anyOf":[{"type":"string","enum":["searchin","graphin","docs","mcp"]},{"type":"null"}],"title":"Created Via","description":"Web client origin (searchin, graphin, docs, or mcp). Ignored for API keys (always OSINTOne API)."},"callback_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Callback Url","description":"Optional https URL that receives a signed POST for each search in the batch when it completes, fails, or is refunded. The event carries ids, status, and cost, never the query or results. Verify it with the secret from GET /v1/webhooks/secret."},"premium":{"type":"boolean","title":"Premium","description":"Defaults to false. When true, OSINT Industries jobs in the batch include premium modules (+$1.80 each). Ignored for other providers.","default":false}},"type":"object","required":["input_type","queries","providers"],"title":"SearchBulkCreateRequest","description":"Request body for creating many searches in one batch (queries × providers).","examples":[{"input_type":"email","providers":["leakradar","dehashed"],"queries":["alice@example.com","bob@example.com"]}]},"SearchBulkResponse":{"properties":{"batch_id":{"type":"string","title":"Batch Id","description":"Durable session UUID stored on every job in this batch."},"input_type":{"type":"string","title":"Input Type"},"total":{"type":"integer","title":"Total"},"estimated_cost_usd":{"type":"string","title":"Estimated Cost Usd","description":"Sum of list prices for all jobs before free-lookup discounts."},"summary":{"$ref":"#/components/schemas/SearchBulkSummary"},"searches":{"items":{"$ref":"#/components/schemas/SearchResponse"},"type":"array","title":"Searches","description":"Jobs in stable order: queries outer, providers inner."}},"type":"object","required":["batch_id","input_type","total","estimated_cost_usd","summary","searches"],"title":"SearchBulkResponse","description":"Bulk search batch: one SearchResponse per (query, provider) job."},"SearchBulkSummary":{"properties":{"completed":{"type":"integer","title":"Completed","default":0},"running":{"type":"integer","title":"Running","default":0},"failed":{"type":"integer","title":"Failed","default":0},"refunded":{"type":"integer","title":"Refunded","default":0},"pending":{"type":"integer","title":"Pending","default":0}},"type":"object","title":"SearchBulkSummary"},"SearchCreateRequest":{"properties":{"provider":{"type":"string","enum":["osint-industries","leakradar","leakosintbot","facecheck","picarta","geoseeer","predicta-search","dehashed","whoxy","whoisxml","securitytrails","snusbase","shodan","hunter","builtwith","blockchair","ipqs"],"title":"Provider","description":"OSINT provider identifier."},"input_type":{"type":"string","enum":["email","username","phone","domain","name","image","ip","crypto"],"title":"Input Type","description":"Type of query value (email, username, domain, etc.)."},"query":{"type":"string","maxLength":2048,"minLength":1,"title":"Query","description":"Search value, normalized and validated per input_type."},"created_via":{"anyOf":[{"type":"string","enum":["searchin","graphin","docs","mcp"]},{"type":"null"}],"title":"Created Via","description":"Web client origin (searchin, graphin, docs, or mcp). Ignored for API keys (always OSINTOne API)."},"callback_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Callback Url","description":"Optional https URL that receives a signed POST when the search completes, fails, or is refunded. The event carries ids, status, and cost, never the query or results. Verify it with the secret from GET /v1/webhooks/secret."},"premium":{"type":"boolean","title":"Premium","description":"OSINT Industries only. Defaults to false — premium modules are not included. Set true to include Snapchat, TikTok, and similar for an extra $1.80.","default":false}},"type":"object","required":["provider","input_type","query"],"title":"SearchCreateRequest","description":"Request body for creating a new OSINT search.","examples":[{"input_type":"email","provider":"leakradar","query":"user@example.com"},{"input_type":"image","provider":"facecheck","query":"https://example.com/photo.jpg"}]},"SearchPremiumRequest":{"properties":{"premium":{"type":"boolean","title":"Premium","description":"Must be true. Runs premium modules on a completed OSINT Industries search.","default":true}},"type":"object","title":"SearchPremiumRequest","description":"Request body for running OSINT Industries premium modules on a completed search."},"SearchQuoteRequest":{"properties":{"provider":{"type":"string","enum":["osint-industries","leakradar","leakosintbot","facecheck","picarta","geoseeer","predicta-search","dehashed","whoxy","whoisxml","securitytrails","snusbase","shodan","hunter","builtwith","blockchair","ipqs"],"title":"Provider","description":"OSINT provider identifier."},"input_type":{"type":"string","enum":["email","username","phone","domain","name","image","ip","crypto"],"title":"Input Type","description":"Type of query value (email, username, domain, etc.)."},"premium":{"type":"boolean","title":"Premium","description":"OSINT Industries only. Price the premium modules (+$1.80) as well.","default":false},"count":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Count","description":"How many lookups of this kind to price, for example the queries in a bulk run.","default":1}},"type":"object","required":["provider","input_type"],"title":"SearchQuoteRequest","description":"Request body for pricing a search without running it.","examples":[{"count":1,"input_type":"email","provider":"leakradar"}]},"SearchQuoteResponse":{"properties":{"provider":{"type":"string","title":"Provider"},"input_type":{"type":"string","title":"Input Type"},"count":{"type":"integer","title":"Count"},"premium":{"type":"boolean","title":"Premium"},"available":{"type":"boolean","title":"Available","description":"False when the provider is turned off; such a search would be rejected."},"unit_cost_usd":{"type":"string","title":"Unit Cost Usd"},"total_cost_usd":{"type":"string","title":"Total Cost Usd"},"balance_usd":{"type":"string","title":"Balance Usd","description":"Current balance of the wallet the API key bills."},"sufficient_balance":{"type":"boolean","title":"Sufficient Balance"},"shortfall_usd":{"type":"string","title":"Shortfall Usd","description":"How much to top up before the search can run; 0.00 when sufficient."},"top_up_url":{"type":"string","title":"Top Up Url"}},"type":"object","required":["provider","input_type","count","premium","available","unit_cost_usd","total_cost_usd","balance_usd","sufficient_balance","shortfall_usd","top_up_url"],"title":"SearchQuoteResponse","description":"Price of a search and whether the active wallet can pay for it. Never charges."},"SearchResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Unique search job UUID."},"status":{"type":"string","enum":["pending","running","completed","failed","refunded"],"title":"Status","description":"Job status. Poll while `running`. `failed` = insufficient balance. `refunded` = charged then upstream failed."},"provider":{"type":"string","title":"Provider","description":"Provider that processed this search."},"input_type":{"type":"string","title":"Input Type","description":"Input type used for the query."},"query":{"type":"string","title":"Query","description":"Normalized query string."},"cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Usd","description":"USD charged for this search."},"balance_after":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Balance After","description":"Account balance after billing action."},"result":{"anyOf":[{"$ref":"#/components/schemas/ProviderResultPayload"},{"type":"null"}],"description":"Results when status is completed."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message when status is failed or refunded."},"poll_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Poll Url","description":"Relative URL to poll when status is running."},"has_stored_result":{"type":"boolean","title":"Has Stored Result","description":"True when this search has a stored result that can be reopened or shared.","default":false},"result_expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Expires At","description":"When stored results expire. Null means lifetime or nothing stored."},"batch_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Batch Id","description":"Session UUID shared by every job from the same submit (one query × N providers)."}},"type":"object","required":["id","status","provider","input_type","query"],"title":"SearchResponse","description":"Search job status and results.","examples":[{"balance_after":"9.00","cost_usd":"1.00","id":"550e8400-e29b-41d4-a716-446655440000","input_type":"email","provider":"leakradar","query":"user@example.com","result":{"matches":[{"added_at":"2025-01-15T10:30:00Z","id":"3f1a9c2b7e","is_email":true,"password":"P@ssw0rd123","password_strength":6,"status":"new","type":"leak","unlocked":true,"url":"https://example.com/login","username":"user@example.com"}],"sources":[{"items_returned":3,"name":"leakradar","page":1,"page_size":100,"total":3,"total_unlocked":2,"type":"email"}]},"status":"completed"},{"balance_after":"9.45","cost_usd":"0.50","id":"550e8400-e29b-41d4-a716-446655440001","input_type":"image","poll_url":"/v1/search/550e8400-e29b-41d4-a716-446655440001","provider":"facecheck","query":"https://example.com/photo.jpg","status":"running"},{"balance_after":"9.00","cost_usd":"0.50","id":"c1e823d0-c8be-486a-aad0-4405a6326c88","input_type":"image","provider":"facecheck","query":"https://example.com/photo.jpg","result":{"matches":[{"score":97,"thumbnail":"data:image/webp;base64,...","url":"https://sports.yahoo.com/article/example"},{"score":94,"thumbnail":"data:image/webp;base64,...","url":"https://www.instagram.com/p/example/"}],"sources":[{"max_score":97,"name":"facecheck","provider":"facecheck","returned":2,"search_id":"c1e823d0-c8be-486a-aad0-4405a6326c88","testing_mode":false,"total_results":300,"type":"image"}]},"status":"completed"},{"balance_after":"0.00","cost_usd":"1.00","error":"Insufficient balance. Required $1.00, available $0.00.","id":"550e8400-e29b-41d4-a716-446655440002","input_type":"email","provider":"leakradar","query":"user@example.com","status":"failed"}]},"SearchUnlockRequest":{"properties":{"unlock_remaining":{"type":"boolean","title":"Unlock Remaining","description":"Must be true. Unlocks leftover LeakRadar credentials on a completed search.","default":true}},"type":"object","title":"SearchUnlockRequest","description":"Request body for unlocking remaining LeakRadar credentials."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"OSINTverse API key (ov_...). Create one at https://osintverse.com/dashboard/api."}}},"tags":[{"name":"health","description":"Service health checks for monitoring and Railway deployments."},{"name":"providers","description":"OSINT provider catalog, supported input types, and per-query pricing in USD."},{"name":"search","description":"Create, poll, and unlock OSINT searches. Requires `x-api-key` authentication."}],"externalDocs":{"description":"Docs for agents (Markdown)","url":"https://osintverse.com/llms.txt"},"servers":[{"url":"https://apiv1.osintverse.com","description":"Production"}]}