{"openapi":"3.1.0","info":{"title":"OSINTverse API","description":"\nProgrammatic access to **SearchIn** — unified OSINT search across LeakRadar, OSINT Industries, Facecheck.id, Picarta.ai, 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 Lite / Plus / Pro** charge a fixed per-query price\nand unlock up to 1,000 / 10,000 / 50,000 credentials respectively.\nIf your balance is insufficient, the search returns `failed` with no charge.\nIf an upstream provider fails after billing, the charge is **refunded** (`refunded` status).\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","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_health_get","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 Lite/Plus/Pro include a max unlock cap. Use this to discover valid `provider` + `input_type` combinations before calling `POST /v1/search`. No authentication required.","operationId":"list_providers_v1_providers_get","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/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.\n\n**Async:** FaceCheck image searches may return `status: running` with a `poll_url`. Poll `GET /v1/search/{id}` every ~2 seconds until complete.","operationId":"create_search_v1_search_post","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-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchCreateRequest"}}}},"responses":{"200":{"description":"Search created. Check `status` for results or polling.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"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."}}}},"/v1/search/{search_id}":{"get":{"tags":["search"],"summary":"Get search status","description":"Retrieve a search job by ID. Use this to **poll async searches** (e.g. FaceCheck) until `status` is `completed`, `failed`, or `refunded`.\n\nRequires **`x-api-key`** header. You can only access searches created by your account.","operationId":"get_search_v1_search__search_id__get","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-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"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"}}}}}}}},"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 tiers only: maximum credential unlocks included in the query price."},"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","id":"leakradar-lite","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 Lite"}]},"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."},"SearchCreateRequest":{"properties":{"provider":{"type":"string","enum":["osint-industries","leakradar-lite","leakradar-plus","leakradar-pro","leakosintbot","facecheck","picarta","predicta-search"],"title":"Provider","description":"OSINT provider identifier."},"input_type":{"type":"string","enum":["email","username","phone","domain","name","image","ip"],"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."}},"type":"object","required":["provider","input_type","query"],"title":"SearchCreateRequest","description":"Request body for creating a new OSINT search.","examples":[{"input_type":"email","provider":"leakradar-lite","query":"user@example.com"},{"input_type":"image","provider":"facecheck","query":"https://example.com/photo.jpg"}]},"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."}},"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-lite","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-lite","query":"user@example.com","status":"failed"}]},"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"}}},"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 and poll OSINT searches. Requires `x-api-key` authentication."}],"servers":[{"url":"https://apiv1.osintverse.com","description":"Production"}]}