{"swagger": "2.0", "basePath": "/", "paths": {"/8k": {"parameters": [{"description": "Filter by stock ticker symbol, uppercase (e.g. MSFT, CRM)", "name": "ticker", "type": "string", "in": "query"}, {"description": "Filter by SEC CIK code (e.g. 0001234567)", "name": "cik", "type": "string", "in": "query"}, {"description": "4-digit filing year (e.g. 2025)", "name": "year", "type": "string", "in": "query"}, {"description": "2-digit filing month, requires `year` (e.g. 06)", "name": "month", "type": "string", "in": "query"}, {"description": "Include Item 1.05 (Material Cybersecurity Incident) filings (default: true)", "type": "boolean", "default": true, "name": "item105", "in": "query"}, {"description": "Include Item 8.01 (Other Events) filings (default: true)", "type": "boolean", "default": true, "name": "item801", "in": "query"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns SEC Form 8-K filings related to cybersecurity incidents, specifically:\n- **Item 1.05** \u2014 Material Cybersecurity Incidents (mandatory since Dec 2023)\n- **Item 8.01** \u2014 Other Events (used for cybersecurity disclosures before Item 1.05)\n\nBy default, both item types are included. Use `item105=false` or `item801=false` to exclude either.\n\n**Examples:**\n- All 2025 filings: `GET /8k?year=2025`\n- Microsoft filings: `GET /8k?ticker=MSFT`\n- Item 1.05 only in Jan 2025: `GET /8k?year=2025&month=01&item801=false`", "operationId": "get_forms8_k", "tags": ["default"]}}, "/csirt/{country}": {"parameters": [{"description": "Country code \u2014 2-letter (e.g. FR) or 3-letter ISO (e.g. FRA)", "name": "country", "in": "path", "required": true, "type": "string"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns all CSIRT/CERT contacts for the given country.\n\nAccepts both ISO 3166-1 **alpha-2** (e.g. `FR`) and **alpha-3** (e.g. `FRA`) codes.\n\nSources: ENISA (EU) and FIRST (global).\n\n**Example:** `GET /csirt/US`", "operationId": "get_csirt_by_country", "tags": ["default"]}}, "/group/{groupname}": {"parameters": [{"description": "Ransomware group name, case-insensitive (e.g. lockbit3, blackcat, clop)", "name": "groupname", "in": "path", "required": true, "type": "string"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns comprehensive intelligence about a specific ransomware group.\n\nResponse includes:\n- `description` \u2014 group background and context\n- `victims` / `firstseen` / `lastseen` \u2014 activity summary\n- `locations` \u2014 known leak site URLs (Tor and clearweb)\n- `ttps` \u2014 MITRE ATT&CK tactics and techniques\n- `vulnerabilities` \u2014 CVEs exploited by this group (with CVSS scores)\n- `tools` \u2014 tools and malware families used\n- `has_negotiations` / `negotiation_count` \u2014 whether chat logs are available\n- `has_ransomnote` / `ransomnotes_count` \u2014 whether ransom notes are available\n\n**Example:** `GET /groups/lockbit3`", "operationId": "get_group_detail", "tags": ["default"]}}, "/groups": {"get": {"responses": {"200": {"description": "Success"}}, "description": "Returns all tracked ransomware groups, sorted alphabetically, with victim counts.\n\nEach entry includes:\n- `group` \u2014 group name (lowercase)\n- `altname` \u2014 alternative/former name if applicable\n- `victims` \u2014 number of active victims attributed to this group\n\nFor full group details (TTPs, tools, YARA, negotiations), use `/groups/<groupname>`.", "operationId": "get_group_list", "tags": ["default"]}}, "/groups/{groupname}": {"parameters": [{"description": "Ransomware group name, case-insensitive (e.g. lockbit3, blackcat, clop)", "name": "groupname", "in": "path", "required": true, "type": "string"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns comprehensive intelligence about a specific ransomware group.\n\nResponse includes:\n- `description` \u2014 group background and context\n- `victims` / `firstseen` / `lastseen` \u2014 activity summary\n- `locations` \u2014 known leak site URLs (Tor and clearweb)\n- `ttps` \u2014 MITRE ATT&CK tactics and techniques\n- `vulnerabilities` \u2014 CVEs exploited by this group (with CVSS scores)\n- `tools` \u2014 tools and malware families used\n- `has_negotiations` / `negotiation_count` \u2014 whether chat logs are available\n- `has_ransomnote` / `ransomnotes_count` \u2014 whether ransom notes are available\n\n**Example:** `GET /groups/lockbit3`", "operationId": "get_group_detail", "tags": ["default"]}}, "/iocs": {"parameters": [{"description": "Optional IOC type filter \u2014 only return groups that have this type (e.g. md5, ip, btc)", "name": "type", "type": "string", "in": "query"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns all ransomware groups that have Indicators of Compromise, with a breakdown of IOC types and counts.\n\nCommon IOC types: `md5`, `sha256`, `ip`, `domain`, `email`, `btc`, `url`.\n\nUse `?type=` to filter to groups that have a specific IOC type. Use `/iocs/<group>` to retrieve the actual indicator values.\n\n**Note:** IOC endpoints are not rate-limited, but fair use applies.", "operationId": "get_ioc_group_list", "tags": ["default"]}}, "/iocs/{group}": {"parameters": [{"description": "Ransomware group name (e.g. lockbit3, blackcat)", "name": "group", "in": "path", "required": true, "type": "string"}, {"description": "Optional: return only this IOC type (e.g. md5, ip, sha256, btc, email)", "name": "type", "type": "string", "in": "query"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns all indicators of compromise for a specific ransomware group, organized by type (e.g. `md5`, `ip`, `domain`).\n\nUse `?type=` to retrieve only one IOC type and reduce response size.\n\n**Note:** IOC endpoints are not rate-limited, but fair use applies.\n\n**Example:** `GET /iocs/lockbit3?type=ip`", "operationId": "get_group_io_cs", "tags": ["default"]}}, "/listsectors": {"get": {"responses": {"200": {"description": "Success"}}, "description": "Returns all unique sector/industry values from the victim database, sorted alphabetically, with a count of victims per sector.\n\nUse the `sector` values returned here as input to the `?sector=` filter in `/victims/` and `/victims/search`.", "operationId": "get_sector_list", "tags": ["default"]}}, "/negotiations": {"get": {"responses": {"200": {"description": "Success"}}, "description": "Lists all ransomware groups that have leaked negotiation chat logs available, with a count of chats per group.\n\nNegotiation chats contain ransom demands, counteroffers, and payment outcomes. Use `/negotiations/<group>` to list individual chats and `/negotiations/<group>/<chat_id>` to read messages.", "operationId": "get_negotiation_groups", "tags": ["default"]}}, "/negotiations/{group}": {"parameters": [{"description": "Ransomware group name (e.g. lockbit3, blackcat)", "name": "group", "in": "path", "required": true, "type": "string"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns metadata for all available negotiation chats for a given ransomware group.\n\nEach chat entry includes:\n- `id` \u2014 chat identifier (use this as `chat_id` in the next endpoint)\n- `message_count` \u2014 total messages in the chat\n- `initialransom` \u2014 initial ransom demand (string, may include currency)\n- `negotiatedransom` \u2014 final negotiated amount (or null)\n- `paid` \u2014 whether the ransom was paid (boolean)", "operationId": "get_negotiation_group_chats", "tags": ["default"]}}, "/negotiations/{group}/{chat_id}": {"parameters": [{"description": "Ransomware group name (e.g. lockbit3)", "name": "group", "in": "path", "required": true, "type": "string"}, {"description": "Chat ID from `/negotiations/<group>` (filename without extension, e.g. 20240517)", "name": "chat_id", "in": "path", "required": true, "type": "string"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns the complete message thread and ransom metadata for a specific negotiation chat.\n\nResponse includes:\n- `initialransom` / `negotiatedransom` \u2014 ransom amounts as strings (format varies by group)\n- `paid` \u2014 boolean, whether payment was confirmed\n- `message_count` \u2014 total messages\n- `messages` \u2014 array of message objects (structure varies by group)", "operationId": "get_negotiation_chat_detail", "tags": ["default"]}}, "/press/all": {"parameters": [{"description": "4-digit year filter (e.g. 2024)", "name": "year", "type": "string", "in": "query"}, {"description": "2-digit month filter, requires `year` (e.g. 03)", "name": "month", "type": "string", "in": "query"}, {"description": "ISO 3166-1 alpha-2 country code (e.g. FR, US)", "name": "country", "type": "string", "in": "query"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns all tracked cyberattack press entries, enriched with HudsonRock infostealer data and a ransomware link if the victim domain matches a known victim.\n\nOptionally filter by year, month, and country. Results are sorted by date descending.\n\n**Example:** `GET /press/all?country=FR&year=2024`", "operationId": "get_press_list", "tags": ["default"]}}, "/press/recent": {"parameters": [{"description": "ISO 3166-1 alpha-2 country code (e.g. FR, US)", "name": "country", "type": "string", "in": "query"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns the 100 most recent cyberattack press entries, enriched with infostealer data and a ransomware link where the victim domain matches.\n\nOptional country filter narrows results to a specific country before selecting the top 100.", "operationId": "get_press_recent", "tags": ["default"]}}, "/ransomnotes": {"get": {"responses": {"200": {"description": "Success"}}, "description": "Lists all ransomware groups that have at least one ransom note on file, with a count of notes per group.\n\nUse `/ransomnotes/<group>` to list filenames and `/ransomnotes/<group>/<note>` to read content.", "operationId": "get_ransomnote_groups", "tags": ["default"]}}, "/ransomnotes/{group}": {"parameters": [{"description": "Ransomware group name (e.g. lockbit3, clop)", "name": "group", "in": "path", "required": true, "type": "string"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns the list of ransom note identifiers (filenames without extension) for a group.\n\nPass a returned name to `/ransomnotes/<group>/<note>` to retrieve the full text content.", "operationId": "get_ransomnote_group_list", "tags": ["default"]}}, "/ransomnotes/{group}/{note_name}": {"parameters": [{"description": "Ransomware group name (e.g. lockbit3)", "name": "group", "in": "path", "required": true, "type": "string"}, {"description": "Note identifier from `/ransomnotes/<group>` (without file extension)", "name": "note_name", "in": "path", "required": true, "type": "string"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns the full text content of a specific ransom note.\n\nSupported formats: `.txt`, `.html`, `.md` (tried in that order).\n\nResponse includes `extension` field indicating which format was found, and `content` with the raw text.", "operationId": "get_ransomnote_detail", "tags": ["default"]}}, "/stats": {"get": {"responses": {"200": {"description": "Success"}}, "description": "Returns high-level statistics: total victim count, number of tracked ransomware groups, number of press/cyberattack entries, and the timestamp of the most recently discovered victim.\n\nResponse fields:\n- `stats.victims` \u2014 active victims (takedown_status \u2260 done)\n- `stats.groups` \u2014 total tracked ransomware groups\n- `stats.press` \u2014 total cyberattack/press entries\n- `last_update` \u2014 ISO 8601 timestamp of the most recently added victim", "operationId": "get_stats", "tags": ["default"]}}, "/validate": {"get": {"responses": {"200": {"description": "Success"}}, "description": "Checks if the provided `X-API-KEY` header is valid and returns the associated client identifier.\n\nUse this endpoint to verify your key is active before making other requests.\n\n**Example:**\n```\ncurl https://api-pro.ransomware.live/validate -H 'X-API-KEY: <your-key>'\n```", "operationId": "get_validate_key", "tags": ["default"]}}, "/victim/{victim_id}": {"parameters": [{"description": "Base64-encoded victim ID (Base64 of 'post_title@group_name')", "name": "victim_id", "in": "path", "required": true, "type": "string"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns enriched details for a single victim.\n\nThe `victim_id` is a Base64-encoded string of `post_title@group_name`. You can obtain it from the `id` field in any victim listing endpoint, or from the `permalink` URL on ransomware.live.\n\nReturns 404 if the victim has been taken down or does not exist.\n\n**Example:** `GET /victim/QWNtZUNvcnBAYWNtZWdyb3Vw` (Base64 of `AcmeCorp@acmegroup`)", "operationId": "get_single_victim", "tags": ["default"]}}, "/victims/": {"parameters": [{"description": "Ransomware group name, case-insensitive exact match (e.g. lockbit, blackcat)", "name": "group", "type": "string", "in": "query"}, {"description": "Victim sector/industry, case-insensitive exact match (e.g. Healthcare, Education). Use `/listsectors` to get valid values.", "name": "sector", "type": "string", "in": "query"}, {"description": "ISO 3166-1 alpha-2 country code, uppercase (e.g. US, FR, DE)", "name": "country", "type": "string", "in": "query"}, {"description": "4-digit year (e.g. 2024). Must be combined with `month` \u2014 `year` alone is rejected.", "name": "year", "type": "string", "in": "query"}, {"description": "2-digit month, requires `year` (e.g. 03)", "name": "month", "type": "string", "in": "query"}, {"description": "Which date field to filter on: `discovered` (default, when ransomware.live first saw the listing) or `attacked` (estimated attack date)", "type": "string", "enum": ["discovered", "attacked"], "default": "discovered", "name": "date", "in": "query"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns victims matching the provided filters. **At least one filter is required.**\n\nAll filters are applied with AND logic \u2014 e.g. `?country=FR&year=2024&month=06` returns only French victims discovered in June 2024.\n\n`year` cannot be used on its own \u2014 it must be paired with `month`.\n\nResults are enriched identically to `/victims/recent` (screenshot, infostealer, press, permalink).\n\n**Examples:**\n- All LockBit victims: `GET /victims/?group=lockbit`\n- US healthcare victims in June 2024: `GET /victims/?country=US&sector=Healthcare&year=2024&month=06`\n- All victims in March 2023: `GET /victims/?year=2023&month=03`", "operationId": "get_victims_all", "tags": ["default"]}}, "/victims/recent": {"parameters": [{"description": "Sort order: `discovered` (default) = date ransomware.live first observed the listing; `attacked` = estimated date of attack", "type": "string", "enum": ["discovered", "attacked"], "default": "discovered", "name": "order", "in": "query"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns the 100 most recent active victims, enriched with screenshot, infostealer data, press coverage, and a permanent permalink.\n\nEach victim object includes:\n- `victim` \u2014 organization name (formerly `post_title`)\n- `group` \u2014 ransomware group name (formerly `group_name`)\n- `attackdate` \u2014 estimated attack/publication date (formerly `published`)\n- `discovered` \u2014 date ransomware.live first observed the listing\n- `country` \u2014 ISO 3166-1 alpha-2 country code\n- `activity` \u2014 victim sector/industry\n- `website` \u2014 victim website domain\n- `screenshot` \u2014 URL to a screenshot of the group's leak page (empty if unavailable)\n- `infostealer` \u2014 HudsonRock infostealer data for the victim domain (empty if none)\n- `press` \u2014 URL to a related press article (null if none)\n- `id` \u2014 Base64-encoded identifier (`post_title@group_name`)\n- `permalink` \u2014 permanent link on ransomware.live", "operationId": "get_recent_victims", "tags": ["default"]}}, "/victims/search": {"parameters": [{"description": "Keyword search \u2014 matches victim name (`post_title`) or website (substring, case-insensitive)", "name": "q", "type": "string", "in": "query"}, {"description": "Ransomware group name, case-insensitive exact match (e.g. lockbit)", "name": "group", "type": "string", "in": "query"}, {"description": "Victim sector, case-insensitive exact match. Use `/listsectors` to get valid values.", "name": "sector", "type": "string", "in": "query"}, {"description": "ISO 3166-1 alpha-2 country code (e.g. US, FR)", "name": "country", "type": "string", "in": "query"}, {"description": "Sort order: `discovered` (default) or `attacked`", "type": "string", "enum": ["discovered", "attacked"], "default": "discovered", "name": "order", "in": "query"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Full-text search across victim names and website domains, with optional secondary filters.\n\nThe `q` keyword is matched as a substring (case-insensitive) against both the victim name and website. Additional filters (`group`, `sector`, `country`) narrow results further \u2014 all active filters use AND logic.\n\nResults are enriched identically to `/victims/recent`.\n\n**Example:** `GET /victims/search?q=hospital&country=US`", "operationId": "get_victim_search", "tags": ["default"]}}, "/yara": {"get": {"responses": {"200": {"description": "Success"}}, "description": "Lists all ransomware groups that have associated YARA detection rules, with a count of rule files per group.\n\nUse `/yara/<group>` to retrieve the actual rule content.", "operationId": "get_yara_rules_list", "tags": ["default"]}}, "/yara/{group}": {"parameters": [{"description": "Ransomware group name (e.g. lockbit3, blackcat)", "name": "group", "in": "path", "required": true, "type": "string"}], "get": {"responses": {"200": {"description": "Success"}}, "description": "Returns all YARA rules for a specific ransomware group.\n\nEach rule entry includes `filename` and `content` (the full `.yar`/`.yara` text). Rules can be used directly with YARA scanners for threat detection.", "operationId": "get_yara_rules_detail", "tags": ["default"]}}}, "info": {"title": "Ransomware.live API PRO", "version": "1.0", "description": "Authenticated REST API providing ransomware threat intelligence data.\n\n**Authentication**: All endpoints require an `X-API-KEY` header. Get your free API key at [ransomware.live/my](https://www.ransomware.live/my).\n\n**Rate limits**: 500,000 requests/month per key. Requests beyond this quota return HTTP 429.\n\n**Date fields**: `attackdate` is the estimated attack/publication date; `discovered` is when ransomware.live first observed the listing.\n\n**Country codes**: Use ISO 3166-1 alpha-2 (2-letter, e.g. `US`, `FR`) unless stated otherwise.\n\nFor more details see [ransomware.live/api](https://www.ransomware.live/api) or contact [support@ransomware.live](mailto:support@ransomware.live).", "termsOfService": "https://www.ransomware.live/t&c"}, "produces": ["application/json"], "consumes": ["application/json"], "securityDefinitions": {"apikey": {"type": "apiKey", "in": "header", "name": "X-API-KEY"}}, "security": [{"apikey": []}], "tags": [{"name": "default", "description": "Default namespace"}], "responses": {"ParseError": {"description": "When a mask can't be parsed"}, "MaskError": {"description": "When any error occurs on mask"}}}