{
  "openapi": "3.1.0",
  "info": {
    "title": "File Hash Analyzer API",
    "version": "0.0.2",
    "description": "Look up MD5, SHA-1 and SHA-256 indicators, submit community reports and explore malware-family statistics.",
    "x-pricing-model": "payg",
    "x-free-tier-calls": 0,
    "x-docs-url": "",
    "x-dakidarts-contract-status": "published",
    "x-dakidarts-execution-status": "source-only"
  },
  "servers": [
    {
      "url": "https://api.dakidarts.com/file-hash-analyzer",
      "description": "Dakidarts direct gateway"
    }
  ],
  "tags": [
    {
      "name": "Operations",
      "description": "Operations endpoints sourced from the File Hash Analyzer API implementation."
    },
    {
      "name": "Analysis",
      "description": "Analysis endpoints sourced from the File Hash Analyzer API implementation."
    },
    {
      "name": "Batch operations",
      "description": "Batch operations endpoints sourced from the File Hash Analyzer API implementation."
    },
    {
      "name": "Cryptography",
      "description": "Cryptography endpoints sourced from the File Hash Analyzer API implementation."
    },
    {
      "name": "Report",
      "description": "Report endpoints sourced from the File Hash Analyzer API implementation."
    },
    {
      "name": "Search",
      "description": "Search endpoints sourced from the File Hash Analyzer API implementation."
    },
    {
      "name": "Recent",
      "description": "Recent endpoints sourced from the File Hash Analyzer API implementation."
    },
    {
      "name": "Families",
      "description": "Families endpoints sourced from the File Hash Analyzer API implementation."
    },
    {
      "name": "Stats",
      "description": "Stats endpoints sourced from the File Hash Analyzer API implementation."
    }
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "Info",
        "description": "Returns the service name, version, and the full endpoint listing. Useful as a \"hello world\" probe.",
        "operationId": "file-hash-analyzer_get_root",
        "tags": [
          "Operations"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          },
          "5XX": {
            "description": "Upstream or gateway error"
          },
          "503": {
            "description": "No live upstream is configured. Sample responses are preview-only."
          }
        },
        "x-dakidarts-execution-status": "source-only",
        "x-dakidarts-source-contract": true
      }
    },
    "/health": {
      "get": {
        "summary": "Health",
        "description": "**Method:** `GET` **Description:** Returns service health status, database row count, last MalwareBazaar sync time, and whether a MalwareBazaar API key is configured.",
        "operationId": "file-hash-analyzer_get_health",
        "tags": [
          "Operations"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "data": {
                      "db": {
                        "status": "ok",
                        "total_hashes": 1117364
                      },
                      "status": "ok",
                      "service": "File Hash Analyzer",
                      "version": "0.0.2",
                      "uptime_s": 3621.45,
                      "last_sync": "2026-08-26T23:34:00+00:00",
                      "malwarebazaar": {
                        "note": "free key at https://auth.abuse.ch/",
                        "api_key_configured": true
                      }
                    },
                    "meta": {
                      "request_id": "a1b2c3d4e5f6",
                      "api_version": "0.0.2"
                    },
                    "success": true
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          },
          "5XX": {
            "description": "Upstream or gateway error"
          },
          "503": {
            "description": "No live upstream is configured. Sample responses are preview-only."
          }
        },
        "x-dakidarts-execution-status": "source-only",
        "x-dakidarts-source-contract": true,
        "x-dakidarts-sample-response": {
          "data": {
            "db": {
              "status": "ok",
              "total_hashes": 1117364
            },
            "status": "ok",
            "service": "File Hash Analyzer",
            "version": "0.0.2",
            "uptime_s": 3621.45,
            "last_sync": "2026-08-26T23:34:00+00:00",
            "malwarebazaar": {
              "note": "free key at https://auth.abuse.ch/",
              "api_key_configured": true
            }
          },
          "meta": {
            "request_id": "a1b2c3d4e5f6",
            "api_version": "0.0.2"
          },
          "success": true
        }
      }
    },
    "/analyze": {
      "get": {
        "summary": "Analyze",
        "description": "**Method:** `GET` or `POST` **Description:** Query the database for a hash to check if it's known malicious, safe, or unknown. Supports MD5, SHA1, and SHA256. If you query with an MD5 or SHA1, the full SHA256 record is returned with `matched_by` indicating how it was resolved.",
        "operationId": "file-hash-analyzer_get_analyze",
        "tags": [
          "Analysis"
        ],
        "parameters": [
          {
            "name": "hash",
            "in": "query",
            "required": true,
            "description": "Hash to check (MD5, SHA1, or SHA256)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "algorithm",
            "in": "query",
            "required": false,
            "description": "`md5`, `sha1`, or `sha256`. Auto-detected if omitted",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          },
          "5XX": {
            "description": "Upstream or gateway error"
          },
          "503": {
            "description": "No live upstream is configured. Sample responses are preview-only."
          }
        },
        "x-dakidarts-execution-status": "source-only",
        "x-dakidarts-source-contract": true
      },
      "post": {
        "summary": "Analyze",
        "description": "**Method:** `GET` or `POST` **Description:** Query the database for a hash to check if it's known malicious, safe, or unknown. Supports MD5, SHA1, and SHA256. If you query with an MD5 or SHA1, the full SHA256 record is returned with `matched_by` indicating how it was resolved.",
        "operationId": "file-hash-analyzer_post_analyze",
        "tags": [
          "Analysis"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "data": {
                      "md5": null,
                      "sha1": null,
                      "tags": "mirai,botnet,iot",
                      "found": true,
                      "votes": 12,
                      "source": "MalwareBazaar",
                      "verdict": "malicious",
                      "file_type": "elf",
                      "confidence": 0.98,
                      "created_at": "2026-08-26T12:00:00+00:00",
                      "first_seen": "2026-01-15",
                      "query_hash": "f50e1120cc6cb993c6f6ba8c734df7855df0cd37cf634d407abffbb9f0660702",
                      "query_algorithm": "sha256"
                    },
                    "meta": {
                      "request_id": "d9ab522232f2",
                      "api_version": "0.0.2"
                    },
                    "success": true
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          },
          "5XX": {
            "description": "Upstream or gateway error"
          },
          "503": {
            "description": "No live upstream is configured. Sample responses are preview-only."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "hash": {
                    "type": "string"
                  },
                  "algorithm": {
                    "type": "string"
                  }
                },
                "required": [
                  "hash"
                ]
              }
            }
          }
        },
        "x-dakidarts-execution-status": "source-only",
        "x-dakidarts-source-contract": true,
        "x-dakidarts-sample-response": {
          "data": {
            "md5": null,
            "sha1": null,
            "tags": "mirai,botnet,iot",
            "found": true,
            "votes": 12,
            "source": "MalwareBazaar",
            "verdict": "malicious",
            "file_type": "elf",
            "confidence": 0.98,
            "created_at": "2026-08-26T12:00:00+00:00",
            "first_seen": "2026-01-15",
            "query_hash": "f50e1120cc6cb993c6f6ba8c734df7855df0cd37cf634d407abffbb9f0660702",
            "query_algorithm": "sha256"
          },
          "meta": {
            "request_id": "d9ab522232f2",
            "api_version": "0.0.2"
          },
          "success": true
        }
      }
    },
    "/analyze/batch": {
      "post": {
        "summary": "Analyze Batch",
        "description": "**Method:** `POST` **Description:** Analyze up to 500 hashes in a single request. Returns individual results for each hash plus a summary with found/not-found/invalid counts.",
        "operationId": "file-hash-analyzer_post_analyze_batch",
        "tags": [
          "Batch operations"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "data": {
                      "results": [
                        {
                          "md5": null,
                          "sha1": null,
                          "tags": "mirai,botnet",
                          "found": true,
                          "votes": 12,
                          "source": "MalwareBazaar",
                          "verdict": "malicious",
                          "file_type": null,
                          "confidence": 0.98,
                          "created_at": "2026-08-26T12:00:00+00:00",
                          "first_seen": null,
                          "query_hash": "f50e1120cc6cb993c6f6ba8c734df7855df0cd37cf634d407abffbb9f0660702",
                          "query_algorithm": "sha256"
                        },
                        {
                          "md5": null,
                          "sha1": null,
                          "tags": [],
                          "found": false,
                          "votes": 0,
                          "source": null,
                          "verdict": "unknown",
                          "file_type": null,
                          "confidence": null,
                          "created_at": null,
                          "first_seen": null,
                          "query_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                          "query_algorithm": "sha256"
                        },
                        {
                          "md5": null,
                          "sha1": null,
                          "tags": [],
                          "error": "Unsupported or undetectable hash algorithm",
                          "found": false,
                          "votes": 0,
                          "source": null,
                          "verdict": "invalid",
                          "file_type": null,
                          "confidence": null,
                          "created_at": null,
                          "first_seen": null,
                          "query_hash": "d41d8cd98f00b204e9800998ecf8427e",
                          "query_algorithm": "md5"
                        }
                      ],
                      "summary": {
                        "found": 1,
                        "total": 3,
                        "invalid": 1,
                        "not_found": 1
                      }
                    },
                    "meta": {
                      "request_id": "a1b2c3d4e5f6",
                      "api_version": "0.0.2",
                      "duration_ms": 1.38
                    },
                    "success": true
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          },
          "5XX": {
            "description": "Upstream or gateway error"
          },
          "503": {
            "description": "No live upstream is configured. Sample responses are preview-only."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "hashes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "hashes"
                ]
              }
            }
          }
        },
        "x-dakidarts-execution-status": "source-only",
        "x-dakidarts-source-contract": true,
        "x-dakidarts-sample-response": {
          "data": {
            "results": [
              {
                "md5": null,
                "sha1": null,
                "tags": "mirai,botnet",
                "found": true,
                "votes": 12,
                "source": "MalwareBazaar",
                "verdict": "malicious",
                "file_type": null,
                "confidence": 0.98,
                "created_at": "2026-08-26T12:00:00+00:00",
                "first_seen": null,
                "query_hash": "f50e1120cc6cb993c6f6ba8c734df7855df0cd37cf634d407abffbb9f0660702",
                "query_algorithm": "sha256"
              },
              {
                "md5": null,
                "sha1": null,
                "tags": [],
                "found": false,
                "votes": 0,
                "source": null,
                "verdict": "unknown",
                "file_type": null,
                "confidence": null,
                "created_at": null,
                "first_seen": null,
                "query_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                "query_algorithm": "sha256"
              },
              {
                "md5": null,
                "sha1": null,
                "tags": [],
                "error": "Unsupported or undetectable hash algorithm",
                "found": false,
                "votes": 0,
                "source": null,
                "verdict": "invalid",
                "file_type": null,
                "confidence": null,
                "created_at": null,
                "first_seen": null,
                "query_hash": "d41d8cd98f00b204e9800998ecf8427e",
                "query_algorithm": "md5"
              }
            ],
            "summary": {
              "found": 1,
              "total": 3,
              "invalid": 1,
              "not_found": 1
            }
          },
          "meta": {
            "request_id": "a1b2c3d4e5f6",
            "api_version": "0.0.2",
            "duration_ms": 1.38
          },
          "success": true
        }
      }
    },
    "/hash/{hash_value}": {
      "get": {
        "summary": "Lookup Rest",
        "description": "**Method:** `GET` **Description:** RESTful single-hash lookup. Same as `/analyze` but the hash goes in the URL path instead of a query parameter. Useful for URL-based integrations and gateway routing.",
        "operationId": "file-hash-analyzer_get_hash_{hash_value}",
        "tags": [
          "Cryptography"
        ],
        "parameters": [
          {
            "name": "hash_value",
            "in": "path",
            "required": true,
            "description": "MD5, SHA-1, or SHA-256 hash to look up in the URL path.",
            "schema": {
              "type": "string",
              "example": "44d88612fea8a8f36de82e1278abb02f"
            },
            "example": "44d88612fea8a8f36de82e1278abb02f"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          },
          "5XX": {
            "description": "Upstream or gateway error"
          },
          "503": {
            "description": "No live upstream is configured. Sample responses are preview-only."
          }
        },
        "x-dakidarts-execution-status": "source-only",
        "x-dakidarts-source-contract": true
      }
    },
    "/report": {
      "post": {
        "summary": "Report",
        "description": "**Method:** `POST` **Description:** Crowdsource a hash, adding a new entry or updating an existing one. If the hash already exists, tags are merged and the vote count increments.",
        "operationId": "file-hash-analyzer_post_report",
        "tags": [
          "Report"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "data": {
                      "entry": {
                        "id": 1117365,
                        "md5": "abc12345678901234567890123456789",
                        "hash": "f50e1120cc6cb993c6f6ba8c734df7855df0cd37cf634d407abffbb9f0660702",
                        "sha1": "def4567890123456789012345678901234567890",
                        "tags": "banker,emotet,trojan",
                        "votes": 1,
                        "source": "InternalSOC",
                        "verdict": "malicious",
                        "algorithm": "sha256",
                        "file_type": "peexe",
                        "created_at": "2026-08-26T23:45:00+00:00",
                        "first_seen": "2026-08-01"
                      },
                      "status": "created"
                    },
                    "meta": {
                      "request_id": "d9ab522232f2",
                      "api_version": "0.0.2"
                    },
                    "success": true
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          },
          "5XX": {
            "description": "Upstream or gateway error"
          },
          "503": {
            "description": "No live upstream is configured. Sample responses are preview-only."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "hash": {
                    "type": "string"
                  },
                  "verdict": {
                    "type": "string"
                  },
                  "algorithm": {
                    "type": "string"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "source": {
                    "type": "string"
                  },
                  "file_type": {
                    "type": "string"
                  },
                  "first_seen": {
                    "type": "string"
                  },
                  "md5": {
                    "type": "string"
                  },
                  "sha1": {
                    "type": "string"
                  }
                },
                "required": [
                  "hash",
                  "verdict"
                ]
              }
            }
          }
        },
        "x-dakidarts-execution-status": "source-only",
        "x-dakidarts-source-contract": true,
        "x-dakidarts-sample-response": {
          "data": {
            "entry": {
              "id": 1117365,
              "md5": "abc12345678901234567890123456789",
              "hash": "f50e1120cc6cb993c6f6ba8c734df7855df0cd37cf634d407abffbb9f0660702",
              "sha1": "def4567890123456789012345678901234567890",
              "tags": "banker,emotet,trojan",
              "votes": 1,
              "source": "InternalSOC",
              "verdict": "malicious",
              "algorithm": "sha256",
              "file_type": "peexe",
              "created_at": "2026-08-26T23:45:00+00:00",
              "first_seen": "2026-08-01"
            },
            "status": "created"
          },
          "meta": {
            "request_id": "d9ab522232f2",
            "api_version": "0.0.2"
          },
          "success": true
        }
      }
    },
    "/report/batch": {
      "post": {
        "summary": "Report Batch",
        "description": "**Method:** `POST` **Description:** Submit up to 100 verdict reports in a single request. Each report follows the same rules as `/report`. Returns per-hash status (created/updated/error) and a summary.",
        "operationId": "file-hash-analyzer_post_report_batch",
        "tags": [
          "Batch operations"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "data": {
                      "results": [
                        {
                          "hash": "f50e1120cc6cb993c6f6ba8c734df7855df0cd37cf634d407abffbb9f0660702",
                          "status": "updated"
                        },
                        {
                          "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                          "status": "created"
                        }
                      ],
                      "summary": {
                        "total": 2,
                        "errors": 0
                      }
                    },
                    "meta": {
                      "request_id": "a1b2c3d4e5f6",
                      "api_version": "0.0.2"
                    },
                    "success": true
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          },
          "5XX": {
            "description": "Upstream or gateway error"
          },
          "503": {
            "description": "No live upstream is configured. Sample responses are preview-only."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reports": {
                    "type": "array",
                    "example": [
                      {
                        "hash": "d41d8cd98f00b204e9800998ecf8427e",
                        "verdict": "malicious"
                      }
                    ],
                    "items": {
                      "type": "object"
                    }
                  }
                },
                "required": [
                  "reports"
                ],
                "example": {
                  "reports": [
                    {
                      "hash": "d41d8cd98f00b204e9800998ecf8427e",
                      "verdict": "malicious"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-dakidarts-execution-status": "source-only",
        "x-dakidarts-source-contract": true,
        "x-dakidarts-sample-response": {
          "data": {
            "results": [
              {
                "hash": "f50e1120cc6cb993c6f6ba8c734df7855df0cd37cf634d407abffbb9f0660702",
                "status": "updated"
              },
              {
                "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                "status": "created"
              }
            ],
            "summary": {
              "total": 2,
              "errors": 0
            }
          },
          "meta": {
            "request_id": "a1b2c3d4e5f6",
            "api_version": "0.0.2"
          },
          "success": true
        }
      }
    },
    "/search": {
      "get": {
        "summary": "Search",
        "description": "**Method:** `GET` **Description:** Search by family/tag name, hex prefix, verdict, or source. Paginated (max 100 per page). If `q` is 6+ hex characters, searches as a hash prefix. Otherwise searches as a family/tag keyword using full-text search. Results are ordered by most recently added.",
        "operationId": "file-hash-analyzer_get_search",
        "tags": [
          "Search"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search query: tag/family name OR hex prefix (6+ hex chars)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "verdict",
            "in": "query",
            "required": false,
            "description": "Filter: `malicious`, `safe`, or `unknown`",
            "schema": {
              "type": "string",
              "enum": [
                "malicious",
                "safe",
                "unknown"
              ]
            }
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "description": "Filter by source substring",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number (default 1)",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Results per page, 1-100 (default 20)",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "data": {
                      "results": [
                        {
                          "id": 1,
                          "md5": null,
                          "hash": "f50e1120cc6cb993c6f6ba8c734df7855df0cd37cf634d407abffbb9f0660702",
                          "sha1": null,
                          "tags": "emotet,banker,trojan",
                          "votes": 12,
                          "source": "MalwareBazaar",
                          "verdict": "malicious",
                          "algorithm": "sha256",
                          "file_type": null,
                          "created_at": "2026-08-26T12:00:00+00:00",
                          "first_seen": "2026-01-15"
                        }
                      ]
                    },
                    "meta": {
                      "page": 1,
                      "pages": 21,
                      "total": 412,
                      "per_page": 20,
                      "request_id": "d9ab522232f2",
                      "api_version": "0.0.2"
                    },
                    "success": true
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          },
          "5XX": {
            "description": "Upstream or gateway error"
          },
          "503": {
            "description": "No live upstream is configured. Sample responses are preview-only."
          }
        },
        "x-dakidarts-execution-status": "source-only",
        "x-dakidarts-source-contract": true,
        "x-dakidarts-sample-response": {
          "data": {
            "results": [
              {
                "id": 1,
                "md5": null,
                "hash": "f50e1120cc6cb993c6f6ba8c734df7855df0cd37cf634d407abffbb9f0660702",
                "sha1": null,
                "tags": "emotet,banker,trojan",
                "votes": 12,
                "source": "MalwareBazaar",
                "verdict": "malicious",
                "algorithm": "sha256",
                "file_type": null,
                "created_at": "2026-08-26T12:00:00+00:00",
                "first_seen": "2026-01-15"
              }
            ]
          },
          "meta": {
            "page": 1,
            "pages": 21,
            "total": 412,
            "per_page": 20,
            "request_id": "d9ab522232f2",
            "api_version": "0.0.2"
          },
          "success": true
        }
      }
    },
    "/recent": {
      "get": {
        "summary": "Recent",
        "description": "**Method:** `GET` **Description:** Browse the most recently added/updated hashes, ordered by creation time descending. Optionally filter by verdict.",
        "operationId": "file-hash-analyzer_get_recent",
        "tags": [
          "Recent"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number (default 1)",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Results per page, 1-100 (default 20)",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "verdict",
            "in": "query",
            "required": false,
            "description": "Filter: `malicious`, `safe`, or `unknown`",
            "schema": {
              "type": "string",
              "enum": [
                "malicious",
                "safe",
                "unknown"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "data": {
                      "results": [
                        {
                          "id": 1117364,
                          "md5": null,
                          "hash": "abc123def456...",
                          "sha1": null,
                          "tags": "mirai,botnet",
                          "votes": 1,
                          "source": "MalwareBazaar",
                          "verdict": "malicious",
                          "algorithm": "sha256",
                          "file_type": null,
                          "created_at": "2026-08-26T23:34:00+00:00",
                          "first_seen": null
                        }
                      ]
                    },
                    "meta": {
                      "page": 1,
                      "pages": 111737,
                      "total": 1117364,
                      "per_page": 10,
                      "request_id": "a1b2c3d4e5f6",
                      "api_version": "0.0.2"
                    },
                    "success": true
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          },
          "5XX": {
            "description": "Upstream or gateway error"
          },
          "503": {
            "description": "No live upstream is configured. Sample responses are preview-only."
          }
        },
        "x-dakidarts-execution-status": "source-only",
        "x-dakidarts-source-contract": true,
        "x-dakidarts-sample-response": {
          "data": {
            "results": [
              {
                "id": 1117364,
                "md5": null,
                "hash": "abc123def456...",
                "sha1": null,
                "tags": "mirai,botnet",
                "votes": 1,
                "source": "MalwareBazaar",
                "verdict": "malicious",
                "algorithm": "sha256",
                "file_type": null,
                "created_at": "2026-08-26T23:34:00+00:00",
                "first_seen": null
              }
            ]
          },
          "meta": {
            "page": 1,
            "pages": 111737,
            "total": 1117364,
            "per_page": 10,
            "request_id": "a1b2c3d4e5f6",
            "api_version": "0.0.2"
          },
          "success": true
        }
      }
    },
    "/families": {
      "get": {
        "summary": "Families",
        "description": "**Method:** `GET` **Description:** Returns a breakdown of malware families (tags) sorted by prevalence. Shows total count plus malicious/safe/unknown sub-counts per family.",
        "operationId": "file-hash-analyzer_get_families",
        "tags": [
          "Families"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max families to return, 1-100 (default 20)",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "data": {
                      "families": [
                        {
                          "safe": 0,
                          "count": 4210,
                          "family": "mirai",
                          "unknown": 10,
                          "malicious": 4200
                        },
                        {
                          "safe": 5,
                          "count": 3800,
                          "family": "heodo",
                          "unknown": 5,
                          "malicious": 3790
                        },
                        {
                          "safe": 0,
                          "count": 2560,
                          "family": "emotet",
                          "unknown": 5,
                          "malicious": 2555
                        },
                        {
                          "safe": 0,
                          "count": 1890,
                          "family": "agenttesla",
                          "unknown": 5,
                          "malicious": 1885
                        },
                        {
                          "safe": 0,
                          "count": 1620,
                          "family": "formbook",
                          "unknown": 5,
                          "malicious": 1615
                        }
                      ],
                      "total_families": 2161
                    },
                    "meta": {
                      "request_id": "d9ab522232f2",
                      "api_version": "0.0.2"
                    },
                    "success": true
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          },
          "5XX": {
            "description": "Upstream or gateway error"
          },
          "503": {
            "description": "No live upstream is configured. Sample responses are preview-only."
          }
        },
        "x-dakidarts-execution-status": "source-only",
        "x-dakidarts-source-contract": true,
        "x-dakidarts-sample-response": {
          "data": {
            "families": [
              {
                "safe": 0,
                "count": 4210,
                "family": "mirai",
                "unknown": 10,
                "malicious": 4200
              },
              {
                "safe": 5,
                "count": 3800,
                "family": "heodo",
                "unknown": 5,
                "malicious": 3790
              },
              {
                "safe": 0,
                "count": 2560,
                "family": "emotet",
                "unknown": 5,
                "malicious": 2555
              },
              {
                "safe": 0,
                "count": 1890,
                "family": "agenttesla",
                "unknown": 5,
                "malicious": 1885
              },
              {
                "safe": 0,
                "count": 1620,
                "family": "formbook",
                "unknown": 5,
                "malicious": 1615
              }
            ],
            "total_families": 2161
          },
          "meta": {
            "request_id": "d9ab522232f2",
            "api_version": "0.0.2"
          },
          "success": true
        }
      }
    },
    "/stats": {
      "get": {
        "summary": "Stats",
        "description": "Database-level statistics.",
        "operationId": "file-hash-analyzer_get_stats",
        "tags": [
          "Stats"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {
                    "safe": 400,
                    "total": 15432,
                    "unknown": 132,
                    "top_tags": [
                      [
                        "emotet",
                        412
                      ],
                      [
                        "agenttesla",
                        300
                      ]
                    ],
                    "last_sync": "2026-08-08T12:00:00.000Z",
                    "malicious": 14900,
                    "top_sources": [
                      [
                        "MalwareBazaar",
                        14800
                      ],
                      [
                        "crowd",
                        632
                      ]
                    ],
                    "top_malicious_tags": [
                      [
                        "emotet",
                        410
                      ]
                    ]
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          },
          "5XX": {
            "description": "Upstream or gateway error"
          },
          "503": {
            "description": "No live upstream is configured. Sample responses are preview-only."
          }
        },
        "x-dakidarts-execution-status": "source-only",
        "x-dakidarts-source-contract": true,
        "x-dakidarts-sample-response": {
          "safe": 400,
          "total": 15432,
          "unknown": 132,
          "top_tags": [
            [
              "emotet",
              412
            ],
            [
              "agenttesla",
              300
            ]
          ],
          "last_sync": "2026-08-08T12:00:00.000Z",
          "malicious": 14900,
          "top_sources": [
            [
              "MalwareBazaar",
              14800
            ],
            [
              "crowd",
              632
            ]
          ],
          "top_malicious_tags": [
            [
              "emotet",
              410
            ]
          ]
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ]
}