{"openapi":"3.1.0","info":{"title":"zertops API","version":"1.0.0","description":"Threat-intelligence lookups for IPs, domains, URLs, file hashes, CVE ids, ASNs and ransomware groups. Anonymous calls are limited per IP; `zt_` API keys from an account raise the limits. Every response carries `X-RateLimit-Remaining` and `X-Quota-Remaining`."},"servers":[{"url":"https://zertops.com"}],"tags":[{"name":"lookup","description":"Anonymous or session-authenticated endpoints."},{"name":"v1","description":"API-key endpoints (Authorization: Bearer zt_...)."}],"paths":{"/api/lookup":{"get":{"tags":["lookup"],"summary":"Look up one indicator","description":"Anonymous: 20/min, 300/day per IP. Signed in: 60/min, 2000/day.","parameters":[{"name":"q","in":"query","required":true,"description":"IP, domain, URL, file hash, CVE id, ASN or ransomware group name. Defanged input is accepted.","schema":{"type":"string","maxLength":2048}},{"name":"refresh","in":"query","required":false,"description":"Force a fresh fetch (10 per hour). Anonymous callers cannot refresh.","schema":{"type":"string","enum":["1"]}},{"name":"private","in":"query","required":false,"description":"Answer from cache and local feeds only; no third-party request is made.","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Lookup result.","headers":{"X-RateLimit-Remaining":{"description":"Tokens left in the per-minute bucket.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Lookups left today (resets at 00:00 UTC).","schema":{"type":"integer"}},"X-Zertops-Cached":{"description":"true when the result came from cache.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResult"}}}},"400":{"description":"invalid_indicator or validation_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"api_key_required or login_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute bucket, see Retry-After) or quota_exceeded (daily cap).","headers":{"X-RateLimit-Remaining":{"description":"Tokens left in the per-minute bucket.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Lookups left today (resets at 00:00 UTC).","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the next request may succeed.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/lookup/batch":{"post":{"tags":["lookup"],"summary":"Look up up to 50 indicators","description":"Each distinct indicator counts against the daily quota. Same-origin only for browsers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["q"],"properties":{"q":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","maxLength":2048},"description":"Raw queries; duplicates are collapsed."},"mode":{"type":"string","enum":["normal","private"],"description":"private answers from cache and local feeds only."}}},"example":{"q":["1.1.1.1","example.com","CVE-2024-3400"]}}}},"responses":{"200":{"description":"One item per distinct query, in order.","headers":{"X-RateLimit-Remaining":{"description":"Tokens left in the per-minute bucket.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Lookups left today (resets at 00:00 UTC).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"400":{"description":"validation_failed or invalid_json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"api_key_required or login_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"body_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"json_required: send application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute bucket, see Retry-After) or quota_exceeded (daily cap).","headers":{"X-RateLimit-Remaining":{"description":"Tokens left in the per-minute bucket.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Lookups left today (resets at 00:00 UTC).","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the next request may succeed.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/lookup/refresh":{"post":{"tags":["lookup"],"summary":"Fetch one indicator again from every source","description":"The Refresh button on result pages. Anonymous: 3/hour, 12/day per IP. Signed in: 10/hour, 60/day. A result younger than a minute is left as is. Same-origin only for browsers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","description":"Indicator type as returned in LookupResult.indicator.type."},"value":{"type":"string","maxLength":2048,"description":"Canonical value as returned in LookupResult.indicator.value."}}}}}},"responses":{"200":{"description":"Whether a new fetch ran.","headers":{"X-RateLimit-Remaining":{"description":"Tokens left in the per-minute bucket.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Lookups left today (resets at 00:00 UTC).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"refreshed":{"type":"boolean"},"reason":{"type":"string","enum":["too_recent","nothing_to_refresh"]},"fetchedAt":{"type":"string","format":"date-time"},"level":{"type":"string"}}}}}},"400":{"description":"invalid_indicator or validation_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"cross_site_request or bad_origin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute bucket, see Retry-After) or quota_exceeded (daily cap).","headers":{"X-RateLimit-Remaining":{"description":"Tokens left in the per-minute bucket.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Lookups left today (resets at 00:00 UTC).","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the next request may succeed.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/lookup/export":{"get":{"tags":["lookup"],"summary":"Download one lookup as CSV, JSON, STIX 2.1 or a MISP event","description":"Same limits as /api/lookup. The response is an attachment named zertops-<type>-<value>.<ext>.","parameters":[{"name":"q","in":"query","required":true,"description":"IP, domain, URL, file hash, CVE id, ASN or ransomware group name. Defanged input is accepted.","schema":{"type":"string","maxLength":2048}},{"name":"format","in":"query","required":true,"schema":{"type":"string","enum":["csv","json","stix","misp"]}}],"responses":{"200":{"description":"The export file.","headers":{"X-RateLimit-Remaining":{"description":"Tokens left in the per-minute bucket.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Lookups left today (resets at 00:00 UTC).","schema":{"type":"integer"}},"X-Zertops-Cached":{"description":"true when the result came from cache.","schema":{"type":"string","enum":["true","false"]}},"Content-Disposition":{"schema":{"type":"string"},"description":"attachment; filename=\"zertops-<type>-<value>.<ext>\""}},"content":{"text/csv":{"schema":{"type":"string"}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/LookupResult"},{"$ref":"#/components/schemas/MispEvent"}]}},"application/stix+json":{"schema":{"$ref":"#/components/schemas/StixBundle"}}}},"400":{"description":"invalid_indicator or validation_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute bucket, see Retry-After) or quota_exceeded (daily cap).","headers":{"X-RateLimit-Remaining":{"description":"Tokens left in the per-minute bucket.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Lookups left today (resets at 00:00 UTC).","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the next request may succeed.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/lookup":{"get":{"tags":["v1"],"summary":"Look up one indicator with an API key","description":"60/min and 2000/day per key.","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"description":"IP, domain, URL, file hash, CVE id, ASN or ransomware group name. Defanged input is accepted.","schema":{"type":"string","maxLength":2048}},{"name":"refresh","in":"query","required":false,"description":"Force a fresh fetch (10 per hour). Anonymous callers cannot refresh.","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Lookup result.","headers":{"X-RateLimit-Remaining":{"description":"Tokens left in the per-minute bucket.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Lookups left today (resets at 00:00 UTC).","schema":{"type":"integer"}},"X-Zertops-Cached":{"description":"true when the result came from cache.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResult"}}}},"400":{"description":"invalid_indicator or validation_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"api_key_required or login_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute bucket, see Retry-After) or quota_exceeded (daily cap).","headers":{"X-RateLimit-Remaining":{"description":"Tokens left in the per-minute bucket.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Lookups left today (resets at 00:00 UTC).","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the next request may succeed.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/lookup/batch":{"post":{"tags":["v1"],"summary":"Look up up to 50 indicators with an API key","description":"60/min per key; every distinct indicator counts against the 2000/day quota.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["q"],"properties":{"q":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","maxLength":2048},"description":"Raw queries; duplicates are collapsed."},"mode":{"type":"string","enum":["normal","private"],"description":"private answers from cache and local feeds only."}}},"example":{"q":["1.1.1.1","example.com","CVE-2024-3400"]}}}},"responses":{"200":{"description":"One item per distinct query, in order.","headers":{"X-RateLimit-Remaining":{"description":"Tokens left in the per-minute bucket.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Lookups left today (resets at 00:00 UTC).","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"400":{"description":"validation_failed or invalid_json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"api_key_required or login_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"body_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"json_required: send application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited (per-minute bucket, see Retry-After) or quota_exceeded (daily cap).","headers":{"X-RateLimit-Remaining":{"description":"Tokens left in the per-minute bucket.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Lookups left today (resets at 00:00 UTC).","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds until the next request may succeed.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"zt_<key>","description":"API key created under Account → API keys. Shown once; stored hashed."}},"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_indicator","validation_failed","invalid_json","json_required","body_too_large","login_required","api_key_required","cross_site_request","bad_origin","rate_limited","quota_exceeded","internal_error"]},"message":{"type":"string"}}},"Indicator":{"type":"object","required":["type","value","display"],"properties":{"type":{"type":"string","enum":["ipv4","ipv6","domain","url","hash_md5","hash_sha1","hash_sha256","ransomware_group","cve","asn"]},"value":{"type":"string","description":"Normalized canonical value."},"display":{"type":"string","description":"Human-friendly form."}}},"Evidence":{"type":"object","required":["source","signal","strength","label"],"properties":{"source":{"type":"string"},"signal":{"type":"string","enum":["malicious","suspicious","clean","info"]},"strength":{"type":"integer","minimum":0,"maximum":100},"label":{"type":"string"},"detail":{"type":"string"}}},"Verdict":{"type":"object","required":["level","score","confidence","reasons"],"properties":{"level":{"type":"string","enum":["malicious","suspicious","benign","unknown"]},"score":{"type":"integer","minimum":0,"maximum":100},"confidence":{"type":"integer","minimum":0,"maximum":100},"reasons":{"type":"array","items":{"$ref":"#/components/schemas/Evidence"},"description":"Strongest first, at most 6."}}},"SourceResult":{"type":"object","required":["source","status","fetchedAt","ttlSeconds","latencyMs","evidence"],"properties":{"source":{"type":"string"},"status":{"type":"string","enum":["ok","not_found","error","timeout","skipped","unconfigured"]},"fetchedAt":{"type":"string","format":"date-time"},"ttlSeconds":{"type":"integer"},"latencyMs":{"type":"integer"},"error":{"type":"string"},"data":{"description":"Capped, provider-specific data.","type":"object","additionalProperties":true},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/Evidence"}}}},"Meta":{"type":"object","required":["cached","fetchedAt","expiresAt","durationMs","sourcesPlanned"],"properties":{"cached":{"type":"boolean"},"fetchedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"durationMs":{"type":"integer"},"sourcesPlanned":{"type":"array","items":{"type":"string"}},"private":{"type":"boolean","description":"Present when no third-party call was made."}}},"LookupResult":{"type":"object","required":["id","indicator","verdict","facts","sources","meta"],"properties":{"id":{"type":"string"},"indicator":{"$ref":"#/components/schemas/Indicator"},"verdict":{"$ref":"#/components/schemas/Verdict"},"facts":{"type":"object","description":"Merged facts for the indicator type; `kind` is ip, domain, url, hash, group, cve or asn. This is what the result page renders.","required":["kind","tags","links"],"properties":{"kind":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"links":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"}}}}},"additionalProperties":true},"sources":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SourceResult"}},"meta":{"$ref":"#/components/schemas/Meta"}}},"BatchItem":{"type":"object","required":["q","ok"],"properties":{"q":{"type":"string"},"ok":{"type":"boolean"},"error":{"type":"string","enum":["invalid_indicator","lookup_failed"]},"result":{"$ref":"#/components/schemas/LookupResult"}}},"BatchResponse":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BatchItem"}}}},"StixBundle":{"type":"object","description":"STIX 2.1 bundle with one indicator, vulnerability (CVE) or intrusion-set (ransomware group). Custom property x_zertops_score carries the 0-100 score.","properties":{"type":{"type":"string","const":"bundle"},"id":{"type":"string"},"objects":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"MispEvent":{"type":"object","description":"MISP event JSON with one attribute per known form of the indicator and a zertops:verdict tag.","properties":{"Event":{"type":"object","additionalProperties":true}}}}}}