API Reference

Get a Malware Sample

Retrieve a single malware sample from the malware sample corpus by its SHA-256 hash, returning key metadata and the detected signature.

GET

/v1/malware/{sha256}

Cost: 1 credit per successful call

Path parameters

sha256stringrequired

SHA-256 hash of the sample, exactly 64 hexadecimal characters (pattern ^[0-9a-f]{64}$). Input is case-insensitive and lowercased server-side before lookup.

Request

curl https://api.precursorintelligence.com/functions/v1/malware/3b4da4eb7b6c4da34e2ed72c558f3ec1a4a3c8a1fdf49fa1e2c5d6a7b8c9d0e1 \
  -H "Authorization: Bearer $PRECURSOR_API_KEY"

Response

200 OK

{
  "data": {
    "sha256_hash": "3b4da4eb7b6c4da34e2ed72c558f3ec1a4a3c8a1fdf49fa1e2c5d6a7b8c9d0e1",
    "sha1_hash": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "md5_hash": "d41d8cd98f00b204e9800998ecf8427e",
    "file_name": "update.dll",
    "file_type": "dll",
    "file_size": 1245120,
    "signature": "QakBot",
    "first_seen": "2026-05-17T08:11:00Z",
    "last_seen": "2026-05-18T01:02:00Z",
    "reporter": "precursor_intelligence",
    "downloads": 14,
    "uploads": 3,
    "tags": ["loader", "banker"],
    "clamav_detections": ["Win.Trojan.Qakbot-12345"],
    "cert_subject_cn": null,
    "cert_issuer_cn": null,
    "cert_cscb_listed": false,
    "generated_at": "2026-05-29T12:00:00Z"
  },
  "meta": {
    "request_id": "8b16efb8-9a6c-4ace-b817-11cbee626d08",
    "generated_at": "2026-05-18T10:24:31.118Z",
    "credits": { "charged": 1, "remaining": 9998 }
  }
}

If the SHA-256 hash is well-formed but does not match any sample in the corpus, the call succeeds with the payload { "error": "not_found", "sha256": "<queried_hash>" } and the credit is refunded automatically.

Response fields

data.sha256_hashstringoptional

SHA-256 hash of the sample.

data.sha1_hashstringoptional

SHA-1 hash of the sample.

data.md5_hashstringoptional

MD5 hash of the sample.

data.file_namestringoptional

Reported file name for the sample.

data.file_typestringoptional

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

data.file_sizeintegeroptional

File size in bytes.

data.signaturestring | nulloptional

Detected malware signature or family name. null when unattributed.

data.first_seenstringoptional

ISO 8601 timestamp when the sample was first observed.

data.last_seenstring | nulloptional

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

data.reporterstringoptional

Identifier of the source that reported the sample.

data.downloadsintegeroptional

Number of times the sample has been downloaded.

data.uploadsintegeroptional

Number of times the sample has been uploaded.

data.tagsarrayoptional

String tags associated with the sample.

data.clamav_detectionsarrayoptional

ClamAV detection names matched against the sample.

data.cert_subject_cnstring | nulloptional

Code-signing certificate subject common name. null when the sample is unsigned.

data.cert_issuer_cnstring | nulloptional

Code-signing certificate issuer common name. null when the sample is unsigned.

data.cert_cscb_listedbooleanoptional

Whether the signing certificate appears on the Code Signing Certificate Blocklist.

data.generated_atstringoptional

ISO 8601 timestamp indicating when this response was generated.

Errors

Status	`error`	When
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 path segment does not match the 64-character hex SHA-256 pattern, or no such route exists.
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.