{"openapi":"3.1.0","info":{"title":"OsintGo Intelligence API","version":"0.1.0","description":"OsintGo is a pay-per-query OSINT intelligence API. Each request runs your query across multiple\nvetted data sources and returns a unified risk score, AI-generated analysis, and structured details.\n\n## Authentication\n\nAll API endpoints (except registration and health) require an `X-API-Key` header containing\nyour personal API key. Keys are prefixed `og_live_` and are issued upon registration.\n\n```\nX-API-Key: og_live_...\n```\n\n## Credits\n\nEach query costs one credit regardless of cache status. Trial accounts start with 3 free credits.\nTop up at any time via the [/v1/account/topup](#tag/Payments/POST/v1/account/topup) endpoint.\n\n## Rate Limits\n\nAll authenticated endpoints are limited to **10 requests per minute** per API key.\nRegistration is limited to **5 requests per hour** per IP address.\n\n## Error Responses\n\nAll errors follow a consistent shape:\n```json\n{\n  \"error\": {\n    \"code\": \"RATE_LIMITED\",\n    \"message\": \"Too many requests. Retry after 1 minute.\",\n    \"request_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n  }\n}\n```\n\n| HTTP Status | When |\n|---|---|\n| 400 | Bad request — missing or invalid parameters |\n| 401 | Missing or invalid API key |\n| 402 | Insufficient credits |\n| 404 | Unsupported query type |\n| 429 | Rate limit exceeded |\n| 500 | Internal server error |\n| 502 | Upstream vendor error |\n| 503 | Service temporarily unavailable |","contact":{"name":"OsintGo Support","url":"https://platform.osintgo.com/dashboard"},"license":{"name":"FAQ","url":"https://www.osintgo.com/faq"}},"servers":[{"url":"https://platform.osintgo.com","description":"Production"}],"tags":[{"name":"Auth","description":"Registration, key recovery, session management"},{"name":"Queries","description":"Intelligence query execution"},{"name":"Scam Detection","description":"Domain reputation and fraud signal analysis"},{"name":"Account","description":"Account info, usage history, credit packages"},{"name":"Payments","description":"Crypto invoice creation and payment history"},{"name":"Misc","description":"Health check, contact form"}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Your OsintGo API key (`og_live_...`). Include on every authenticated request."}},"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMITED"},"message":{"type":"string","example":"Too many requests. Retry after 1 minute."},"request_id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"}}}}},"UnifiedQueryResponse":{"type":"object","required":["risk_score","risk_signals","ai_analysis","details","meta"],"description":"Every query type returns this shape. The `details` object is source-specific.","properties":{"risk_score":{"type":"integer","minimum":0,"maximum":100,"description":"0–19 minimal · 20–39 low · 40–59 medium · 60–79 high · 80–100 critical","example":65},"risk_signals":{"type":"array","items":{"type":"string"},"description":"Concrete, human-readable findings that drove the risk score.","example":["Email found in 7 breaches","Passwords exposed in 3 breaches","Found in stealer log paste"]},"ai_analysis":{"type":"string","description":"2–3 sentence AI-generated narrative summarising risk and key observations.","example":"Associated with John Smith. The address appears in 7 data breaches including LinkedIn and Adobe, with passwords exposed in 3 of them. The presence in a recent stealer log paste indicates an elevated risk of active credential abuse."},"details":{"type":"object","description":"Source-specific structured data — shape varies by query type. See individual query type schemas below.","example":{"email":"target@example.com","breach_count":7,"breaches":[]}},"meta":{"type":"object","required":["sources_queried","sources_failed","response_time_ms","cache_hit"],"properties":{"sources_queried":{"type":"integer","example":3},"sources_failed":{"type":"integer","example":0},"response_time_ms":{"type":"integer","example":1840},"cache_hit":{"type":"boolean","description":"True if result was served from cache. Credits are still charged.","example":false}}}}},"EmailLookupDetails":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":["string","null"],"description":"Real name if discovered across data sources."},"breach_count":{"type":"integer"},"breaches":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"date":{"type":"string","format":"date"},"data_classes":{"type":"array","items":{"type":"string"}}}}}},"example":{"email":"target@example.com","name":"Jane Doe","breach_count":4,"breaches":[{"name":"LinkedIn","date":"2021-06-22","data_classes":["Email addresses","Passwords"]},{"name":"Adobe","date":"2013-10-04","data_classes":["Email addresses","Password hints","Usernames"]}]}},"IpLookupDetails":{"type":"object","properties":{"ip":{"type":"string","format":"ipv4"},"country":{"type":["string","null"]},"city":{"type":["string","null"]},"asn":{"type":["string","null"]},"isp":{"type":["string","null"]},"is_proxy":{"type":"boolean"},"is_vpn":{"type":"boolean"},"is_tor":{"type":"boolean"},"open_ports":{"type":"array","items":{"type":"integer"}}},"example":{"ip":"198.51.100.42","country":"US","city":"Ashburn","asn":"AS14618 Amazon.com Inc.","isp":"Amazon AWS","is_proxy":false,"is_vpn":true,"is_tor":false,"open_ports":[80,443]}},"PhoneLookupDetails":{"type":"object","properties":{"phone":{"type":"string"},"name":{"type":["string","null"]},"carrier":{"type":["string","null"]},"line_type":{"type":"string","enum":["mobile","landline","voip","unknown"]},"country":{"type":["string","null"]},"breach_count":{"type":"integer"},"breaches":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"date":{"type":"string","format":"date"},"data_classes":{"type":"array","items":{"type":"string"}}}}}},"example":{"phone":"+12025551234","name":"John Smith","carrier":"T-Mobile","line_type":"mobile","country":"US","breach_count":2,"breaches":[{"name":"Facebook","date":"2019-04-14","data_classes":["Phone numbers","Email addresses"]}]}},"DomainLookupDetails":{"type":"object","properties":{"domain":{"type":"string"},"registrar":{"type":["string","null"]},"registered_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"registrant_country":{"type":["string","null"]},"nameservers":{"type":"array","items":{"type":"string"}},"mx_records":{"type":"array","items":{"type":"string"}},"has_spf":{"type":"boolean"},"has_dmarc":{"type":"boolean"},"ssl_valid":{"type":["boolean","null"]},"ssl_issuer":{"type":["string","null"]}},"example":{"domain":"suspicious-exchange.io","registrar":"NameCheap, Inc.","registered_at":"2024-09-03T00:00:00Z","expires_at":"2025-09-03T00:00:00Z","registrant_country":"PA","nameservers":["ns1.cloudflare.com","ns2.cloudflare.com"],"mx_records":[],"has_spf":false,"has_dmarc":false,"ssl_valid":true,"ssl_issuer":"Let's Encrypt"}},"UsernameLookupDetails":{"type":"object","properties":{"username":{"type":"string"},"name":{"type":["string","null"],"description":"Real name if discovered."},"platforms":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":["string","null"],"format":"uri"}}},"description":"Social platforms and forums where the username was found."},"breach_count":{"type":"integer"},"breaches":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"date":{"type":"string","format":"date"},"data_classes":{"type":"array","items":{"type":"string"}}}}}},"example":{"username":"jdoe_hacker","name":"John Doe","platforms":[{"name":"GitHub","url":"https://github.com/jdoe_hacker"},{"name":"HackerNews","url":null}],"breach_count":2,"breaches":[{"name":"LinkedIn","date":"2021-06-22","data_classes":["Usernames","Email addresses"]}]}},"NameLookupDetails":{"type":"object","properties":{"name":{"type":"string","description":"The searched name."},"emails":{"type":"array","items":{"type":"string","format":"email"}},"phones":{"type":"array","items":{"type":"string"}},"breach_count":{"type":"integer"},"breaches":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"date":{"type":"string","format":"date"},"data_classes":{"type":"array","items":{"type":"string"}}}}}},"example":{"name":"Jane Doe","emails":["jane.doe@gmail.com","jdoe@company.io"],"phones":["+12025551234"],"breach_count":3,"breaches":[{"name":"LinkedIn","date":"2021-06-22","data_classes":["Email addresses","Passwords"]}]}},"WalletLookupDetails":{"type":"object","properties":{"address":{"type":"string"},"currency":{"type":["string","null"]},"name":{"type":["string","null"],"description":"Entity or cluster name if attributed."},"breach_count":{"type":"integer"},"breaches":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"date":{"type":"string","format":"date"},"data_classes":{"type":"array","items":{"type":"string"}}}}}},"example":{"address":"0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD","currency":"ETH","name":"Uniswap Universal Router","breach_count":0,"breaches":[]}},"CryptoTraceDetails":{"type":"object","properties":{"address":{"type":"string","description":"The queried blockchain address."},"currency":{"type":"string","description":"e.g. BTC, ETH, USDT"},"category":{"type":["string","null"],"description":"Cluster category (e.g. exchange, darknet market, mixer, ransomware)."},"entity_name":{"type":["string","null"],"description":"Named entity if attributed by intelligence providers."}},"example":{"address":"1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf Na","currency":"BTC","category":"mining","entity_name":"Genesis Block"}},"BreachSearchDetails":{"type":"object","properties":{"identifier":{"type":"string"},"breach_count":{"type":"integer"},"breaches":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"date":{"type":"string","format":"date"},"records_count":{"type":["integer","null"]},"data_classes":{"type":"array","items":{"type":"string"}},"verified":{"type":"boolean"}}}},"first_seen":{"type":["string","null"],"format":"date"},"last_seen":{"type":["string","null"],"format":"date"}}},"ScamDetectionResponse":{"type":"object","required":["risk_score","risk_signals","ai_analysis","details"],"properties":{"risk_score":{"type":"integer","minimum":0,"maximum":100,"example":82},"risk_signals":{"type":"array","items":{"type":"string"},"example":["Domain registered only 14 days ago","No MX records — no email infrastructure","Missing SPF record","Missing DMARC record"]},"ai_analysis":{"type":"string","example":"The domain suspicious-exchange.io was registered 14 days ago in Panama with no email infrastructure, which is a strong indicator of a newly-created fraudulent site. The absence of SPF, DMARC, and MX records is consistent with a domain created solely for phishing or exit scam purposes. Treat with extreme caution."},"details":{"type":"object","properties":{"domain":{"type":"string"},"risk_tier":{"type":"string","enum":["clean","low","medium","high","critical"]},"verdict":{"type":"string"},"vasp_name":{"type":["string","null"]},"vasp_category":{"type":["string","null"]},"vasp_licensed":{"type":["boolean","null"]},"domain_age_days":{"type":["integer","null"]},"registered_at":{"type":["string","null"]},"registrar":{"type":["string","null"]},"country":{"type":["string","null"]},"ssl_valid":{"type":["boolean","null"]},"ssl_issuer":{"type":["string","null"]},"has_spf":{"type":"boolean"},"has_dmarc":{"type":"boolean"},"nameservers":{"type":"array","items":{"type":"string"}},"mx_records":{"type":"array","items":{"type":"string"}},"community_reports":{"type":["integer","null"]},"community_sources":{"type":"array","items":{"type":"string"}}},"example":{"domain":"suspicious-exchange.io","risk_tier":"critical","verdict":"High likelihood of fraud — newly registered domain with no legitimate infrastructure.","vasp_name":null,"vasp_category":null,"vasp_licensed":null,"domain_age_days":14,"registered_at":"2024-09-03","registrar":"NameCheap, Inc.","country":"PA","ssl_valid":true,"ssl_issuer":"Let's Encrypt","has_spf":false,"has_dmarc":false,"nameservers":["ns1.cloudflare.com"],"mx_records":[],"community_reports":3,"community_sources":["reddit.com","bitcointalk.org"]}}}},"AccountResponse":{"type":"object","properties":{"tier":{"type":"string","enum":["trial","paid"]},"queries_used":{"type":"integer","example":7},"queries_limit":{"type":"integer","example":100},"queries_remaining":{"type":"integer","example":93},"email":{"type":["string","null"],"format":"email"},"created_at":{"type":"string","format":"date-time"}}},"CreditPackage":{"type":"object","properties":{"id":{"type":"string","example":"starter"},"credits":{"type":"integer","example":50},"price_usd":{"type":"number","example":25},"label":{"type":"string","example":"Starter — 50 queries"},"per_query":{"type":"string","example":"$0.50/query"}}},"UsageLog":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"endpoint":{"type":"string","example":"/v1/query"},"vendor_source":{"type":"string","example":"email_lookup"},"response_time_ms":{"type":"integer","example":1240},"status":{"type":"string","enum":["success","error","partial"]},"cost_credits":{"type":"integer","example":1},"query_input":{"type":"object","description":"Sanitised copy of the original request body."},"query_cache":{"type":["object","null"],"properties":{"output":{"type":"object"}}}}},"Payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"crypto_currency":{"type":"string","enum":["BTC","XMR","ETH","USDT"]},"amount":{"type":"number"},"status":{"type":"string","enum":["pending","confirmed","expired"]},"credits_granted":{"type":"integer"},"btcpay_invoice_id":{"type":["string","null"]}}}}},"security":[],"paths":{"/health":{"get":{"tags":["Misc"],"operationId":"getHealth","summary":"Health check","description":"Returns worker liveness. Append `?deep=1` to also probe Supabase and Redis (returns 503 if degraded).","parameters":[{"name":"deep","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"Set to `1` for a deep health check that tests database and cache connectivity."}],"responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"version":{"type":"string","example":"0.1.0"},"uptime":{"type":"integer","example":3600,"description":"Seconds since process start."}}}}}},"503":{"description":"Degraded — one or more dependencies unreachable (deep check only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/register":{"post":{"tags":["Auth"],"operationId":"register","summary":"Register — step 1","description":"Submit your email to start registration. A magic link is sent to your inbox.\nThe account is **not** created until you click the link (step 2).\n\nRate limited to 5 requests per IP per hour.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","example":"you@example.com"},"cf_turnstile_token":{"type":"string","description":"Cloudflare Turnstile token (required on production)."}}}}}},"responses":{"202":{"description":"Magic link sent (also returned when email already exists — prevents enumeration)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Check your email. A confirmation link has been sent."}}}}}},"400":{"description":"Invalid email format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many registrations from this IP","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/register/confirm":{"get":{"tags":["Auth"],"operationId":"confirmRegistration","summary":"Register — step 2","description":"Exchange the magic link token for a new account and API key.\nThe token is consumed after a single use and expires after **1 hour**.\n\n> **Save your API key immediately** — it is only shown once.","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string","example":"a3f9...d72b"},"description":"One-time token from the magic link email."}],"responses":{"201":{"description":"Account created — API key issued","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string","example":"og_live_f2a4d6...","description":"Your permanent API key. Store it securely — it will not be shown again."},"tier":{"type":"string","example":"trial"},"queries_limit":{"type":"integer","example":3},"warning":{"type":"string","example":"Save your API key — it cannot be recovered or shown again."}}}}}},"400":{"description":"Missing or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Email already registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Too many failed confirmation attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/recover":{"post":{"tags":["Auth"],"operationId":"recoverKey","summary":"Recover API key — step 1","description":"Submit your registered email to receive a recovery link.\nAlways returns the same response to prevent email enumeration.\n\nRecovery tokens expire after **15 minutes**.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"cf_turnstile_token":{"type":"string","description":"Cloudflare Turnstile token (required on production)."}}}}}},"responses":{"200":{"description":"Recovery email sent (same response whether email is registered or not)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"400":{"description":"Invalid email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/recover/confirm":{"post":{"tags":["Auth"],"operationId":"confirmRecovery","summary":"Recover API key — step 2","description":"Exchange a recovery token for a brand new API key.\nThe **old key is revoked immediately** upon success.\n\n> **Save your new API key immediately** — it is only shown once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","example":"b8c1...e45f"}}}}}},"responses":{"200":{"description":"New API key issued — old key revoked","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string","example":"og_live_a9c3e7..."},"warning":{"type":"string"}}}}}},"400":{"description":"Missing or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/auth/session":{"post":{"tags":["Auth"],"operationId":"createSession","summary":"Log login event","description":"Called by the dashboard after a successful API key validation. Writes an access log entry.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Logged","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true}}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"tags":["Auth"],"operationId":"deleteSession","summary":"Log logout event","description":"Called by the dashboard when the user signs out. Writes an access log entry.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Logged","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true}}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/account":{"get":{"tags":["Account"],"operationId":"getAccount","summary":"Get account info","description":"Returns your tier, credit balance, and account metadata.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Account info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountResponse"},"example":{"tier":"paid","queries_used":47,"queries_limit":200,"queries_remaining":153,"email":"you@example.com","created_at":"2025-01-15T10:30:00Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/account/packages":{"get":{"tags":["Account"],"operationId":"listPackages","summary":"List credit packages","description":"Returns all available credit packages with pricing. No auth required.","responses":{"200":{"description":"Available packages","content":{"application/json":{"schema":{"type":"object","properties":{"packages":{"type":"array","items":{"$ref":"#/components/schemas/CreditPackage"}}}},"example":{"packages":[{"id":"starter","credits":50,"price_usd":25,"label":"Starter — 50 queries","per_query":"$0.50/query"},{"id":"pro","credits":250,"price_usd":100,"label":"Pro — 250 queries","per_query":"$0.40/query"},{"id":"enterprise","credits":1000,"price_usd":300,"label":"Enterprise — 1,000 queries","per_query":"$0.30/query"}]}}}}}}},"/v1/account/usage":{"get":{"tags":["Account"],"operationId":"getUsage","summary":"Query history","description":"Returns paginated query logs for the authenticated account.","security":[{"ApiKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100},"description":"Max results per page."},{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Pagination offset."}],"responses":{"200":{"description":"Paginated logs","content":{"application/json":{"schema":{"type":"object","properties":{"logs":{"type":"array","items":{"$ref":"#/components/schemas/UsageLog"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/account/query-stats":{"get":{"tags":["Account"],"operationId":"getQueryStats","summary":"Query type statistics","description":"Returns a breakdown of queries by type for your account (last 500 queries).","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Stats by query type","content":{"application/json":{"schema":{"type":"object","properties":{"stats":{"type":"array","items":{"type":"object","properties":{"query_type":{"type":"string","example":"email_lookup"},"count":{"type":"integer","example":23}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/account/topup":{"post":{"tags":["Payments"],"operationId":"createTopup","summary":"Create crypto invoice","description":"Creates a new payment invoice for a credit package.\n\nSupported currencies: **BTC**, **XMR**, **USDT** (via BTCPay), **ETH** (direct on-chain).\n\nCredits are added automatically once the payment is confirmed on-chain.","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["package_id","currency"],"properties":{"package_id":{"type":"string","description":"ID from GET /v1/account/packages","example":"starter"},"currency":{"type":"string","enum":["BTC","XMR","USDT","ETH"],"example":"BTC"}}}}}},"responses":{"200":{"description":"Invoice created","content":{"application/json":{"schema":{"oneOf":[{"title":"BTC / XMR / USDT","type":"object","properties":{"invoice_id":{"type":"string"},"checkout_url":{"type":"string","format":"uri","description":"BTCPay checkout page."},"payment_id":{"type":"string","format":"uuid"},"expires_in_minutes":{"type":"integer","example":60},"credits":{"type":"integer","example":50},"price_usd":{"type":"number","example":25},"currency":{"type":"string","example":"BTC"}}},{"title":"ETH","type":"object","properties":{"invoice_id":{"type":"string"},"eth_address":{"type":"string","description":"Send ETH exactly to this address."},"eth_expected_wei":{"type":"string","description":"Exact amount in wei."},"payment_id":{"type":"string","format":"uuid"},"expires_in_minutes":{"type":"integer","example":60},"credits":{"type":"integer","example":50},"price_usd":{"type":"number","example":25},"currency":{"type":"string","example":"ETH"}}}]}}}},"400":{"description":"Invalid package or currency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Package not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/account/payments":{"get":{"tags":["Payments"],"operationId":"listPayments","summary":"Payment history","description":"Returns paginated payment records for the authenticated account.","security":[{"ApiKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","confirmed","expired"]},"description":"Filter by payment status."}],"responses":{"200":{"description":"Paginated payments","content":{"application/json":{"schema":{"type":"object","properties":{"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/query/types":{"get":{"tags":["Queries"],"operationId":"listQueryTypes","summary":"List supported query types","description":"Returns all query types currently available on the platform.","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Supported query types","content":{"application/json":{"schema":{"type":"object","properties":{"query_types":{"type":"array","items":{"type":"string"},"example":["email_lookup","ip_lookup","phone_lookup","domain_lookup","username_lookup","name_lookup","wallet_lookup","crypto_trace"]}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/query":{"post":{"tags":["Queries"],"operationId":"runQuery","summary":"Run intelligence query","description":"Execute an OSINT query. Each call consumes **one credit** — even cache hits.\n\nResults are normalised by an AI summariser into a unified schema:\n- `risk_score` — integer 0–100\n- `risk_signals` — concrete findings driving the score\n- `ai_analysis` — 2–3 sentence narrative\n- `details` — source-specific structured object (schema varies by `query_type`)\n\n### Query types\n\n| Type | Required param | Description |\n|---|---|---|\n| `email_lookup` | `email` | Breach history, identity profiles |\n| `ip_lookup` | `ip` | Geolocation, proxy/VPN/Tor detection, abuse flags |\n| `phone_lookup` | `phone` | Carrier, line type, breach records |\n| `domain_lookup` | `domain` | Registrar, DNS, SSL, breach records for a domain |\n| `username_lookup` | `username` | Social platform presence, breach records |\n| `name_lookup` | `name` | Associated emails, phones, and breach exposure |\n| `wallet_lookup` | `address` | Wallet address identity and breach records |\n| `crypto_trace` | `address`, `currency` | Blockchain attribution and illicit exposure |\n\nUse `GET /v1/query/types` to get the live list including any newly added types.","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query_type","params"],"properties":{"query_type":{"type":"string","description":"The type of intelligence query to run.","example":"email_lookup"},"params":{"type":"object","description":"Query parameters — structure depends on `query_type`.","example":{"email":"target@example.com"}},"vendors":{"type":"array","items":{"type":"string"},"description":"Optional: restrict to specific vendor slugs. Omit to use all available vendors for the query type."}}},"examples":{"email_lookup":{"summary":"Email lookup","value":{"query_type":"email_lookup","params":{"email":"target@example.com"}}},"ip_lookup":{"summary":"IP lookup","value":{"query_type":"ip_lookup","params":{"ip":"198.51.100.42"}}},"phone_lookup":{"summary":"Phone lookup","value":{"query_type":"phone_lookup","params":{"phone":"+12025551234"}}},"domain_lookup":{"summary":"Domain lookup","value":{"query_type":"domain_lookup","params":{"domain":"suspicious-exchange.io"}}},"username_lookup":{"summary":"Username lookup","value":{"query_type":"username_lookup","params":{"username":"jdoe_hacker"}}},"name_lookup":{"summary":"Name lookup","value":{"query_type":"name_lookup","params":{"name":"Jane Doe"}}},"wallet_lookup":{"summary":"Wallet lookup","value":{"query_type":"wallet_lookup","params":{"address":"0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD"}}},"crypto_trace":{"summary":"Crypto address trace (Chainalysis)","value":{"query_type":"crypto_trace","params":{"address":"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa","currency":"BTC"}}}}}}},"responses":{"200":{"description":"Query result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnifiedQueryResponse"},"examples":{"email_lookup_result":{"summary":"Email lookup result","value":{"risk_score":65,"risk_signals":["Email found in 7 breaches","Passwords exposed in 3 breaches","Found in stealer log paste"],"ai_analysis":"Associated with Jane Doe. The address appears in 7 data breaches including LinkedIn and Adobe, with passwords exposed in 3 of them. The presence in a recent stealer log paste indicates an elevated risk of active credential abuse.","details":{"email":"target@example.com","name":"Jane Doe","breach_count":7,"breaches":[{"name":"LinkedIn","date":"2021-06-22","data_classes":["Email addresses","Passwords"]},{"name":"Adobe","date":"2013-10-04","data_classes":["Email addresses","Password hints"]}]},"meta":{"sources_queried":3,"sources_failed":0,"response_time_ms":1840,"cache_hit":false}}},"ip_lookup_result":{"summary":"IP lookup result","value":{"risk_score":35,"risk_signals":["VPN detected (Amazon AWS datacenter)","Associated ASN hosts many VPN services"],"ai_analysis":"The IP 198.51.100.42 resolves to Amazon AWS infrastructure in Ashburn, US, and is flagged as a VPN exit node. While no active abuse reports are on record, the datacenter ASN and VPN classification indicate anonymised traffic. Treat as medium confidence attribution.","details":{"ip":"198.51.100.42","country":"US","city":"Ashburn","asn":"AS14618 Amazon.com Inc.","isp":"Amazon AWS","is_proxy":false,"is_vpn":true,"is_tor":false,"open_ports":[443]},"meta":{"sources_queried":2,"sources_failed":0,"response_time_ms":910,"cache_hit":false}}},"crypto_trace_result":{"summary":"Crypto trace result","value":{"risk_score":10,"risk_signals":["Address attributed to known mining pool"],"ai_analysis":"The Bitcoin address is attributed to the Genesis Block mining entity, the first Bitcoin block mined by Satoshi Nakamoto in January 2009. This is a historically significant address with no illicit exposure or suspicious counterparty interactions.","details":{"address":"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa","currency":"BTC","category":"mining","entity_name":"Genesis Block"},"meta":{"sources_queried":1,"sources_failed":0,"response_time_ms":620,"cache_hit":false}}}}}}},"400":{"description":"Invalid request body or parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Unsupported query type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded (10 req/min)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Upstream vendor error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/scam-detection":{"post":{"tags":["Scam Detection"],"operationId":"analyzeScamDomain","summary":"Analyse domain for fraud signals","description":"Runs a comprehensive multi-signal analysis of a domain to assess fraud risk.\n\n**Signals checked:**\n- Domain age and registration metadata (WHOIS)\n- DNS infrastructure (SPF, DMARC, MX records, nameservers)\n- SSL certificate validity and issuer\n- URL structure patterns common to phishing sites\n- Community scam reports (via web search)\n- VASP database — checks if the domain is a known crypto exchange\n\nResults are normalised into the unified output shape with a `risk_tier` classification:\n\n| Tier | Score range |\n|---|---|\n| clean | 0–19 |\n| low | 20–39 |\n| medium | 40–59 |\n| high | 60–79 |\n| critical | 80–100 |\n\nConsumes **one credit**. Results are cached.","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","minLength":3,"maxLength":253,"description":"Domain name without protocol or path.","example":"suspicious-exchange.io"}}}}}},"responses":{"200":{"description":"Analysis result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScamDetectionResponse"}}}},"400":{"description":"Invalid domain format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/contact":{"post":{"tags":["Misc"],"operationId":"submitContact","summary":"Contact form","description":"Submit a support or general enquiry. Turnstile CAPTCHA required in production. Rate limited to 3 requests per IP per hour.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject","message","reply_email"],"properties":{"subject":{"type":"string","enum":["Support","Privacy Request","Ethics Concern","General"],"example":"Support"},"message":{"type":"string","minLength":10,"maxLength":5000,"example":"I need help accessing my account."},"reply_email":{"type":"string","format":"email","example":"you@example.com"},"cf_turnstile_token":{"type":"string","description":"Cloudflare Turnstile token (required on production)."}}}}}},"responses":{"200":{"description":"Submitted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}