API Reference

Search Malware Samples

Search the malware sample corpus by substring match across file name, signature, or hash values. Returns paginated results ordered by most recently seen.

This endpoint shares the /v1/malware collection path with Get a Malware Sample; the two are selected by the query parameter you supply. Pass q for a substring search, or request /v1/malware/{sha256} for an exact lookup by hash.

GET

/v1/malware

Cost: 1 credit per successful call

Query parameters

qstringrequired

Substring to match against file name, signature, SHA-256, SHA-1, or MD5 hash. Accepted range: 3–200 characters.

file_typestringoptional

Filter results to a specific file type (for example, exe, dll, apk). Maximum 32 characters.

signaturestringoptional

Filter results to a specific malware signature or family name. Maximum 80 characters.

pageintegeroptionaldefault: 1

Page number for paginated results. Accepted range: 1–20.

page_sizeintegeroptionaldefault: 25

Number of items per page. Accepted range: 1–100.

Request

curl "https://api.precursorintelligence.com/functions/v1/malware?q=qakbot&file_type=dll&signature=QakBot&page=1&page_size=25" \
  -H "Authorization: Bearer $PRECURSOR_API_KEY"

Response

200 OK

{
  "data": {
    "count": 1,
    "items": [
      {
        "sha256_hash": "a3f1e2b94c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2",
        "sha3_384_hash": null,
        "sha1_hash": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
        "md5_hash": "d41d8cd98f00b204e9800998ecf8427e",
        "file_name": "update.dll",
        "file_size": 1245120,
        "file_type": "dll",
        "file_type_mime": "application/x-dosexec",
        "file_format": "PE32",
        "file_arch": "x86",
        "first_seen": "2026-05-17T08:11:00Z",
        "last_seen": "2026-05-19T12:04:00Z",
        "reporter": "analyst_42",
        "anonymous": false,
        "origin_country": "RU",
        "signature": "QakBot",
        "imphash": "7f4b9c2d1e8a3f6b0c5d2e9a4b7f1c3d",
        "tlsh": "T1A3A0027B2E8...",
        "telfhash": null,
        "gimphash": null,
        "ssdeep": "24576:abc123def456:xyz",
        "dhash_icon": null,
        "magika": "pebin",
        "trid": null,
        "archive_pw": null,
        "delivery_method": "email",
        "tags": ["dll", "QakBot", "dropped-by-emotet"],
        "intelligence": {"downloads": 12, "uploads": 1, "mail": {}},
        "code_signing": null,
        "yara_rules": [{"rule_name": "QakBot_loader", "author": "ditekshen", "description": "Detects QakBot loader", "reference": "https://github.com/ditekshen/detection"}],
        "vendor_intelligence": {},
        "comments": [],
        "references": [],
        "context": {},
        "file_information": {},
        "created_at": "2026-05-17T08:15:00Z",
        "updated_at": "2026-05-19T12:10:00Z"
      }
    ],
    "generated_at": "2026-05-29T10:24:31.118Z"
  },
  "meta": {
    "request_id": "8b16efb8-9a6c-4ace-b817-11cbee626d08",
    "generated_at": "2026-05-18T10:24:31.118Z",
    "credits": { "charged": 1, "remaining": 9998 }
  }
}

Response fields

data.countintegeroptional

Number of samples returned (equals items.length).

data.itemsarrayoptional

Matching malware samples, ordered most recently seen first. Each object contains the fields below.

data.items[].sha256_hashstringoptional

SHA-256 hash of the sample.

data.items[].sha1_hashstringoptional

SHA-1 hash of the sample.

data.items[].md5_hashstringoptional

MD5 hash of the sample.

data.items[].file_namestringoptional

Reported file name for the sample.

data.items[].file_sizeintegeroptional

File size in bytes.

data.items[].file_typestringoptional

Short file-type identifier, for example dll or exe.

data.items[].signaturestring | nulloptional

Detected malware signature or family name. null when unattributed.

data.items[].first_seenstringoptional

ISO 8601 timestamp when the sample was first observed.

data.items[].last_seenstring | nulloptional

ISO 8601 timestamp when the sample was most recently observed. May be null.

data.items[].tagsarrayoptional

String tags associated with the sample.

data.items[].intelligenceobjectoptional

Aggregate intelligence counters such as downloads, uploads, and mail.

data.items[].yara_rulesarrayoptional

Matching YARA rules. Each object contains rule_name, author, description, and reference.

data.generated_atstringoptional

ISO 8601 timestamp indicating when this response was generated.

Additional sample metadata fields — including sha3_384_hash, file_type_mime, file_format, file_arch, reporter, anonymous, origin_country, imphash, tlsh, telfhash, gimphash, ssdeep, dhash_icon, magika, trid, archive_pw, delivery_method, code_signing, vendor_intelligence, comments, references, context, file_information, created_at, and updated_at — are returned per item as shown in the example above. Any field may be null or an empty object/array when unavailable.

Errors

Status	`error`	When
400	`missing_query`	`q` was not supplied.
400	`invalid_q`, `invalid_file_type`, `invalid_signature`, `invalid_page`, `invalid_page_size`	A parameter failed validation.
401	`invalid_authorization`	Missing or malformed `Authorization` header.
401	`unauthorized`	Invalid/revoked key, or IP not allowlisted.
402	`insufficient_credits`	Organisation credit balance is below 1.
404	`not_found`	The route or entity does not exist.
405	`method_not_allowed`	Only `GET` and `OPTIONS` are accepted.
500	`internal`	Unexpected server error (credit auto-refunded).

See Errors for the full error reference.