{
  "openapi":"3.1.0",
  "info":{"title":"cull API","version":"1.0.0","description":"Vulnerability search API for product versions, package coordinates, and vulnerability identifiers."},
  "servers":[{"url":"https://cull.sh/api/v1"}],
  "paths":{
    "/search":{"get":{"summary":"Search one product or vulnerability","parameters":[
      {"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"x-max-base-utf8-bytes":512},"description":"Product/version, CPE, PURL or vulnerability identifier plus optional research directives. The resolved base target portion may be at most 512 UTF-8 bytes."},
      {"name":"filter","in":"query","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"description":"Repeatable finding directive, applied before totals and cursor pagination. Separate directives use logical AND. Signals: is:kev, is:exploit, is:needs-review. Exploit evidence: tool:metasploit, tool:nuclei, tool:exploit-db, tool:unverified-poc, tool:unreviewed-exploit; comma-separated tool values use logical OR. Other filters include fixed:true, certainty:certain, cvss:>=7, epss:>=10%, published:>=2025-01-01, primitive:CWE-22 and CVSS base metrics such as vector:AV:N or vector:PR:L. Supported base metric keys are AV, AC, AT, AU, PR, UI, S, C, I, A, VC, VI, VA, SC, SI and SA.","examples":{"observed":{"summary":"Known exploitation","value":["is:kev"]},"network-critical":{"summary":"Critical network-reachable findings","value":["cvss:>=9","vector:AV:N"]},"selected-tooling":{"summary":"Either Metasploit or Nuclei","value":["tool:metasploit,nuclei"]}}},
      {"name":"sort","in":"query","schema":{"type":"string","enum":["priority","cvss","epss","published","id"],"default":"priority"}},
      {"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"default":50},"description":"Maximum results per collection. Values above 500 are accepted and capped at 500."},
      {"name":"include","in":"query","schema":{"type":"string"},"description":"Comma-separated ruled_out and unchecked."},
	  {"name":"view","in":"query","schema":{"type":"string","enum":["ids"]},"description":"Return affected vulnerability IDs, aliases and applicability counts without presentation or diagnostic objects. Uses ID ordering and cannot be combined with filters or include."},
      {"name":"cursor","in":"query","schema":{"type":"string"}},
      {"name":"ruled_out_cursor","in":"query","schema":{"type":"string"}},
      {"name":"unchecked_cursor","in":"query","schema":{"type":"string"}}
	],"responses":{"200":{"description":"Search result","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SearchResult"},{"$ref":"#/components/schemas/IdentifierSearchResult"}]}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/RetryableUnavailable"},"504":{"$ref":"#/components/responses/Error"}}}},
    "/bulk":{"post":{"summary":"Search up to 100 queries","parameters":[{"name":"findings","in":"query","schema":{"type":"integer","enum":[1]},"description":"Set to 1 to include up to 25 CVE summaries per query; use each search_url for complete cursor traversal."}],"requestBody":{"required":true,"description":"The complete request body may be at most 65,536 bytes. Blank lines, comment lines beginning with #, and duplicate queries are removed before the 100-query limit is applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkRequest"},"example":{"queries":["openssl 1.0.1","joomla 1.5 is:exploit"]}},"text/plain":{"schema":{"type":"string","minLength":1,"x-max-utf8-bytes":65536},"example":"openssl 1.0.1\njoomla 1.5 is:exploit\n"}}},"responses":{"200":{"description":"Per-query summaries with explicit truncation state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/RetryableUnavailable"}}}},
    "/trending":{"get":{"summary":"List the most-discussed CVEs in the last seven days","responses":{"200":{"description":"Daily privacy-minimized mention ranking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrendingResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/RetryableUnavailable"}}}},
    "/wordpress":{"get":{"summary":"List recent WordPress vulnerabilities newest first","parameters":[{"name":"window","in":"query","required":false,"description":"Days back to consider","schema":{"type":"integer","minimum":1,"maximum":180,"default":30}},{"name":"limit","in":"query","required":false,"description":"Records to return","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"vector","in":"query","required":false,"description":"Comma-separated CVSS base metrics that must all be present. Pass empty to clear. A record with no vector matches none.","schema":{"type":"string","default":"AV:N,PR:N"}},{"name":"severity","in":"query","required":false,"description":"That band and above. Anything but any excludes records with no score.","schema":{"type":"string","enum":["any","low","medium","high","critical"],"default":"high"}}],"responses":{"200":{"description":"Newest-first WordPress records from the Wordfence corpus","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/RateLimited"}}}}
  },
  "components":{
    "headers":{"RetryAfter":{"description":"Minimum number of seconds the client must wait before retrying.","schema":{"type":"integer","minimum":1}}},
    "responses":{"Error":{"description":"Stable machine-readable error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Request budget exhausted","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RetryableUnavailable":{"description":"Service temporarily unavailable","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},
    "schemas":{
      "Error":{"type":"object","required":["code","error"],"properties":{"code":{"type":"string","enum":["invalid_request","invalid_cursor","request_too_large","forbidden","rate_limited","temporarily_unavailable","timeout","internal_error"]},"error":{"type":"string"}}},
      "TrendingItem":{"type":"object","required":["cve"],"properties":{"cve":{"type":"string","pattern":"^CVE-[0-9]{4}-[0-9]{4,19}$"},"summary":{"type":"string","maxLength":160}}},
      "WordPressResponse":{"type":"object","required":["dataset_id","built_at","window_days","filter","items"],"properties":{"dataset_id":{"type":"string"},"built_at":{"type":"string","format":"date-time"},"window_days":{"type":"integer","minimum":1,"maximum":180},"filter":{"$ref":"#/components/schemas/WordPressFilter"},"items":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/WordPressItem"}}}},
      "WordPressFilter":{"type":"object","required":["vector","severity","min_cvss"],"properties":{"vector":{"type":"array","items":{"type":"string"},"description":"CVSS base metrics required, empty when cleared"},"severity":{"type":"string","enum":["any","low","medium","high","critical"]},"min_cvss":{"type":"number","description":"Score floor the severity name resolves to"}}},
      "WordPressItem":{"type":"object","required":["id","published","rank","access"],"properties":{"id":{"type":"string","description":"CVE, or a WORDFENCE- identifier when no CVE was assigned"},"published":{"type":"string","format":"date"},"rank":{"type":"integer","minimum":1,"description":"Position in the filtered newest-first response"},"product":{"type":"string"},"summary":{"type":"string"},"access":{"type":"string","enum":["unauthenticated","low-privilege","granted-role","administrator","unstated"]},"impact":{"type":"string"},"cwe":{"type":"string"},"cvss":{"type":"number"},"cvss_vector":{"type":"string"},"unpatched":{"type":"boolean"},"uncatalogued":{"type":"boolean"}}},
      "TrendingResponse":{"type":"object","required":["updated_at","window_days","stale","items"],"properties":{"updated_at":{"type":"string","format":"date-time"},"window_days":{"type":"integer","const":7},"stale":{"type":"boolean"},"items":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/TrendingItem"}}}},
      "BulkRequest":{"type":"object","required":["queries"],"properties":{"queries":{"type":"array","minItems":1,"x-max-cleaned-items":100,"items":{"type":"string"},"description":"Queries are trimmed; blanks, comments and duplicates are removed, then requests with more than 100 remaining queries receive HTTP 413. An individual query above 512 UTF-8 bytes produces a per-query request_too_large result."}}},
      "Lifecycle":{"type":"object","required":["status","product","version","release_cycle","source"],"properties":{"status":{"type":"string","enum":["supported","security_only","extended_support","eol"]},"product":{"type":"string"},"version":{"type":"string"},"release_cycle":{"type":"string"},"latest_in_cycle":{"type":"string"},"recommended_version":{"type":"string"},"active_support_end":{"type":"string","format":"date"},"standard_support_end":{"type":"string","format":"date"},"eol_date":{"type":"string","format":"date"},"source":{"type":"string"},"source_url":{"type":"string","format":"uri"},"release_policy_url":{"type":"string","format":"uri"}},"description":"Version-specific upstream support status. This is lifecycle context, not evidence that a vulnerability applies."},
      "BulkResult":{"type":"object","required":["query","status","total_findings","total_ruled_out","total_unchecked","known_exploited","with_exploit","findings_truncated"],"properties":{"query":{"type":"string"},"status":{"type":"string","enum":["AFFECTED","NOT_AFFECTED","UNKNOWN_OR_UNCHECKED","UNRESOLVED"]},"product":{"type":"string"},"version":{"type":"string"},"lifecycle":{"$ref":"#/components/schemas/Lifecycle"},"total_findings":{"type":"integer","minimum":0},"total_ruled_out":{"type":"integer","minimum":0},"total_unchecked":{"type":"integer","minimum":0},"known_exploited":{"type":"integer","minimum":0},"with_exploit":{"type":"integer","minimum":0},"max_cvss":{"type":"number"},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"findings_truncated":{"type":"boolean"},"search_url":{"type":"string"},"alternatives":{"type":"array","items":{"type":"string"}},"trace":{"type":"array","items":{"$ref":"#/components/schemas/Trace"}},"error_code":{"type":"string","enum":["invalid_request","request_too_large","not_found","ambiguous_product"]},"error":{"type":"string"}}},
      "BulkResponse":{"type":"object","required":["results","queries","elapsed","truncated"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/BulkResult"}},"queries":{"type":"integer","minimum":1,"maximum":100},"elapsed":{"type":"string"},"dataset_id":{"type":"string"},"built_at":{"type":"string","format":"date-time"},"truncated":{"type":"boolean","description":"True only when the 20-second execution deadline omitted remaining queries. Requests above 100 cleaned queries fail with HTTP 413 and are not partially processed."}}},
      "Context":{"type":"object","required":["distro","label","advisories","active"],"properties":{"distro":{"type":"string"},"release":{"type":"string"},"label":{"type":"string"},"package_key":{"type":"string"},"advisories":{"type":"integer","minimum":0},"active":{"type":"boolean"}}},
      "Reference":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"kind":{"type":"string","enum":["metasploit","nuclei","exploit-db","unverified-poc","unreviewed-exploit"]},"tags":{"type":"array","items":{"type":"string"}},"published":{"type":"string","format":"date"},"metric":{"type":"string"},"score":{"type":"number"}}},
      "TimelineEvent":{"type":"object","required":["kind","date"],"properties":{"kind":{"type":"string","enum":["published","modified","fixed","kev-added","kev-due","exploit-metasploit","exploit-exploit-db","exploit-poc"]},"date":{"type":"string","format":"date"},"detail":{"type":"string"},"url":{"type":"string","format":"uri"},"source":{"type":"string"},"vuln_id":{"type":"string"}}},
      "Verdict":{"type":"object","required":["source","reason"],"properties":{"source":{"type":"string"},"vuln_id":{"type":"string"},"published":{"type":"string","format":"date"},"modified":{"type":"string","format":"date"},"reason":{"type":"string"},"product_key":{"type":"string"},"range":{"type":"string"},"fixed_in":{"type":"string"},"release":{"type":"string"},"branch":{"type":"string"},"distro":{"type":"string"},"note":{"type":"string"}}},
      "VerdictGroup":{"type":"object","required":["source","reason","count"],"properties":{"source":{"type":"string"},"vuln_id":{"type":"string"},"product_key":{"type":"string"},"published":{"type":"string","format":"date"},"modified":{"type":"string","format":"date"},"reason":{"type":"string"},"range":{"type":"string"},"fixed_in":{"type":"string"},"branch":{"type":"string"},"note":{"type":"string"},"releases":{"type":"array","items":{"type":"string"}},"count":{"type":"integer"},"url":{"type":"string","format":"uri"}}},
      "AttackPrimitive":{"type":"object","required":["name","cwe","confidence"],"properties":{"name":{"type":"string"},"cwe":{"type":"string"},"confidence":{"type":"string","enum":["cwe-derived"]}}},
      "Attribution":{"type":"object","required":["holder"],"properties":{"holder":{"type":"string"},"notice":{"type":"string"},"license":{"type":"string"},"license_url":{"type":"string","format":"uri"},"record_url":{"type":"string","format":"uri"},"message":{"type":"string"}}},
      "ExploitCommand":{"type":"object","required":["tool","label","command","reference"],"properties":{"tool":{"type":"string","enum":["metasploit","nuclei","exploitdb","poc"]},"label":{"type":"string"},"command":{"type":"string"},"reference":{"type":"string","format":"uri"}}},
      "Correction":{"type":"object","required":["name","product","advisories"],"properties":{"name":{"type":"string"},"product":{"type":"string"},"advisories":{"type":"integer","minimum":0}}},
      "Trace":{"type":"object","required":["step","detail","uncertain"],"properties":{"step":{"type":"string"},"detail":{"type":"string"},"uncertain":{"type":"boolean"}}},
      "CVSSAssessment":{"type":"object","required":["cvss"],"properties":{"cvss":{"type":"number"},"severity":{"type":"string"},"cvss_vector":{"type":"string"},"cvss_kind":{"type":"string"},"scorer":{"type":"string"}}},"Finding":{"type":"object","required":["id","reason","has_exploit","action_group","certain","confirming_sources","tracking_sources","verdicts","fix_status"],"properties":{"id":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"reason":{"type":"string"},"withdrawn":{"type":"boolean","description":"The complete merged record has been rejected or withdrawn; exact identifier lookups still return it for traceability."},"review_reason":{"type":"string","enum":["target_details_missing","description_derived","advisory_data_incomplete"]},"cvss":{"type":"number"},"severity":{"type":"string"},"cvss_vector":{"type":"string"},"cvss_kind":{"type":"string"},"cvss_scorer":{"type":"string","description":"Who produced the reported score."},"cvss_alternatives":{"type":"array","description":"Scores other sources gave the same vulnerability, present only when they disagree with the reported one.","items":{"$ref":"#/components/schemas/CVSSAssessment"}},"epss":{"type":"number"},"epss_band":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"desc_line":{"type":"string","description":"Title when available, otherwise the description; intended for compact result lists."},"cwes":{"type":"array","items":{"type":"string"}},"attack_primitives":{"type":"array","items":{"$ref":"#/components/schemas/AttackPrimitive"}},"known_exploited":{"type":"array","items":{"type":"string"}},"ssvc":{"type":"string"},"has_exploit":{"type":"boolean"},"exploit_tier":{"type":"string","enum":["unreviewed","proof-of-concept","verifiable","weaponized","observed"]},"action_group":{"type":"string","enum":["act_now","fixable","investigate"]},"sources_disagree":{"type":"boolean"},"exploit_commands":{"type":"array","items":{"$ref":"#/components/schemas/ExploitCommand"}},"certain":{"type":"boolean"},"confirming_sources":{"type":"integer","minimum":0},"tracking_sources":{"type":"integer","minimum":0},"verdicts":{"type":"array","items":{"$ref":"#/components/schemas/Verdict"}},"verdict_groups":{"type":"array","items":{"$ref":"#/components/schemas/VerdictGroup"}},"exploits":{"type":"array","items":{"$ref":"#/components/schemas/Reference"}},"references":{"type":"array","items":{"$ref":"#/components/schemas/Reference"}},"attributions":{"type":"array","items":{"$ref":"#/components/schemas/Attribution"}},"published":{"type":"string","format":"date"},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEvent"}},"fixed_in":{"type":"array","items":{"type":"string"}},"fix_target":{"type":"string"},"fix_status":{"type":"string","enum":["available","ambiguous","none"]},"fix_options":{"type":"array","items":{"type":"string"}}}},
	  "IdentifierFinding":{"type":"object","required":["id","reason","certain","confirming_sources","tracking_sources"],"properties":{"id":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"reason":{"type":"string"},"certain":{"type":"boolean"},"confirming_sources":{"type":"integer","minimum":0},"tracking_sources":{"type":"integer","minimum":0}}},
	  "IdentifierSearchResult":{"type":"object","required":["query","status","findings","truncated","total_findings","total_ruled_out","elapsed"],"properties":{"query":{"type":"string"},"status":{"type":"string","enum":["AFFECTED","NOT_AFFECTED","UNKNOWN_OR_UNCHECKED","UNRESOLVED"]},"dataset_id":{"type":"string"},"built_at":{"type":"string","format":"date-time"},"product":{"type":"string"},"version":{"type":"string"},"vuln_ids":{"type":"array","items":{"type":"string"}},"distro":{"type":"string"},"interpreted_id":{"type":"string"},"interpreted_kind":{"type":"string","enum":["cpe","purl"]},"product_aliases":{"type":"array","items":{"type":"string"}},"findings":{"type":"array","items":{"$ref":"#/components/schemas/IdentifierFinding"}},"truncated":{"type":"boolean"},"total_findings":{"type":"integer","minimum":0},"total_ruled_out":{"type":"integer","minimum":0},"total_unchecked":{"type":"integer","minimum":0},"next_cursor":{"type":"string"},"alternatives":{"type":"array","items":{"type":"string"}},"corrections":{"type":"array","items":{"$ref":"#/components/schemas/Correction"}},"elapsed":{"type":"string"}}},
      "SearchResult":{"type":"object","required":["query","status","findings","truncated","total_findings","total_ruled_out","elapsed"],"properties":{"query":{"type":"string"},"status":{"type":"string","description":"Applicability before research filters. AFFECTED means a product finding was confirmed for the requested version or an exact vulnerability-ID lookup retrieved a known record; uncertain product evidence remains UNKNOWN_OR_UNCHECKED. Filters never turn an affected or unchecked base result into an all-clear. UNRESOLVED means the query matched no product and nothing was checked.","enum":["AFFECTED","NOT_AFFECTED","UNKNOWN_OR_UNCHECKED","UNRESOLVED"]},"dataset_id":{"type":"string"},"built_at":{"type":"string","format":"date-time"},"product":{"type":"string"},"version":{"type":"string"},"lifecycle":{"$ref":"#/components/schemas/Lifecycle"},"vuln_ids":{"type":"array","items":{"type":"string"}},"distro":{"type":"string"},"interpreted_id":{"type":"string"},"interpreted_kind":{"type":"string","enum":["cpe","purl"]},"product_aliases":{"type":"array","items":{"type":"string"}},"available_contexts":{"type":"array","items":{"$ref":"#/components/schemas/Context"}},"distro_without_data":{"type":"string","description":"The distribution the query named when no source stated anything about it. The answer then rests on upstream version ranges alone, so a fix this distribution backported is not visible in it."},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"ruled_out":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"unchecked":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"truncated":{"type":"boolean"},"total_findings":{"type":"integer","minimum":0},"total_ruled_out":{"type":"integer","minimum":0},"total_unchecked":{"type":"integer","minimum":0},"next_cursor":{"type":"string"},"next_ruled_out_cursor":{"type":"string"},"next_unchecked_cursor":{"type":"string"},"alternatives":{"type":"array","items":{"type":"string"}},"corrections":{"type":"array","items":{"$ref":"#/components/schemas/Correction"}},"trace":{"type":"array","items":{"$ref":"#/components/schemas/Trace"}},"elapsed":{"type":"string"}}}
    }
  }
}