CIRCL hashlookup API
Free CIRCL hashlookup API with no key: check MD5, SHA-1 or SHA-256 file hashes against NSRL and other known-good datasets to filter out legitimate system files.
Endpoint tested and returned HTTP 200 on 2026-08-21
What is the CIRCL hashlookup API?
The CIRCL hashlookup API is a free, key-free service that checks a file hash against large collections of known files, principally the NIST National Software Reference Library. A match tells you the file is a known, catalogued piece of software, with its filename, size and originating product.
Most hash-lookup services answer the question "is this malicious?". hashlookup answers the opposite and arguably more useful one: "is this a known-good file I can stop looking at?". In forensics and incident response the bottleneck is volume — hundreds of thousands of files on a disk image, nearly all of them stock operating system components — and matching against NSRL removes the noise so analysts can concentrate on what is left.
The example shows what a hit looks like: a Windows timezone resource manifest, matched by MD5, attributed to a specific cumulative update for Windows Server 2016. Two fields deserve care. `hashlookup:trust` is a 0-100 confidence in the record rather than a verdict on the file, and a value of 50 is unremarkable. More importantly, a match means the hash appears in a catalogue of known software, not that the file is safe: NSRL includes plenty of software that is unwanted in a corporate environment, and attackers have been known to abuse legitimate signed binaries. Treat a hit as a reason to deprioritise, not as an all-clear. A bulk POST endpoint accepts many hashes at once and is the right tool for a whole disk image.
Quick facts
- Base URL
https://hashlookup.circl.lu- Authentication
- No API key or account. CIRCL provides hashlookup as a free public service for the security community; the underlying NSRL data is US government work.
- Rate limit
- No published limit for reasonable use. For whole-image processing use the bulk POST endpoint, or the offline Bloom filter CIRCL distributes for local matching.
- Pricing
- Free, with no registration.
- CORS
- Not enabled — call it from your server
- Official docs
- Read the docs
How to use the CIRCL hashlookup API
Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.
1. Look up a file by its MD5 hash
GET https://hashlookup.circl.lu/lookup/md5/8ED4B4ED952526D89899E723F3488DE4
curl 'https://hashlookup.circl.lu/lookup/md5/8ED4B4ED952526D89899E723F3488DE4' \
-H 'Accept: application/json'const res = await fetch("https://hashlookup.circl.lu/lookup/md5/8ED4B4ED952526D89899E723F3488DE4", {
headers: {
"Accept": "application/json",
},
});
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);import requests
headers = {
"Accept": "application/json",
}
res = requests.get("https://hashlookup.circl.lu/lookup/md5/8ED4B4ED952526D89899E723F3488DE4", headers=headers, timeout=20)
res.raise_for_status()
print(res.json()){
"CRC32": "7A5407CA",
"FileName": "wow64_microsoft-windows-i..timezones.resources_31bf3856ad364e35_10.0.16299.579_de-de_f24979c73226184d.manifest",
"FileSize": "2520",
"MD5": "8ED4B4ED952526D89899E723F3488DE4",
"OpSystemCode": {
"MfgCode": "1006",
"OpSystemCode": "362",
"OpSystemName": "TBD",
"OpSystemVersion": "none"
},
"ProductCode": {
"ApplicationType": "Security",
"Language": "Multilanguage",
"MfgCode": "608",
"OpSystemCode": "868",
"ProductCode": "190742",
"ProductName": "Cumulative Update for Windows Server 2016 for x64 (KB4338817)",
"ProductVersion": "1709"
},
"SHA-1": "00000079FD7AAC9B2F9C988C50750E1F50B27EB5",
"SpecialCode": "",
"db": "nsrl_modern_rds",
"insert-timestamp": "1646977909.0909765",
"source": "NSRL",
"hashlookup:trust": 50
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
algorithm | path segment | Required | Hash algorithm: `md5`, `sha1` or `sha256`. md5 |
hash | path segment | Required | The hash value in hexadecimal. Case-insensitive. 8ED4B4ED952526D89899E723F3488DE4 |
(endpoint) /bulk/md5 | path | Optional | POST a JSON array of hashes to look up many at once. /bulk/md5 |
(endpoint) /children/{sha1} | path | Optional | Files contained within a known archive or installer. /children/00000079FD... |
(endpoint) /parents/{sha1} | path | Optional | Packages or archives that contain the given file. /parents/00000079FD... |
(endpoint) /stats/top | path | Optional | Service statistics and the most frequently queried hashes. /stats/top |
Response fields
FileNamestring- Catalogued filename for the hash. Attackers rename files, so this is the original name, not necessarily what you found.
FileSizestring- File size in bytes, as a string.
MD5 / SHA-1 / CRC32string- The other hashes of the same file, letting you pivot between algorithms.
ProductCode.ProductName / ProductVersionstring- The software product the file shipped with — often precise enough to name the exact patch.
OpSystemCodeobject- Operating system the file is associated with, where known.
sourcestring- Which dataset matched, such as `NSRL`. CIRCL aggregates several.
dbstring- The specific database within the source, for example `nsrl_modern_rds`.
hashlookup:trustinteger- 0-100 confidence in the record itself. Not a safety verdict on the file.
What you can build with the CIRCL hashlookup API
- Filter known operating system files out of a forensic disk image
- Reduce noise in an incident response triage queue
- Identify which Windows update a mystery file came from
- Deduplicate a large file collection by known-software status
- Enrich EDR telemetry with known-file context
Common errors and how to fix them
404
The hash is not in any indexed dataset.
Fix: This is the common case and means nothing on its own — most files in the world are not in NSRL. It is not evidence of maliciousness.
Slow bulk lookups
Looping over single-hash requests.
Fix: POST to `/bulk/{algorithm}` with an array of hashes. One request replaces thousands.
Assuming a hit means safe
A match means catalogued, not benign.
Fix: NSRL includes unwanted and dual-use software, and legitimate signed binaries get abused. Use a hit to deprioritise, never to clear.
Case or format mismatch
Hashes must be plain hexadecimal.
Fix: Strip whitespace and any `md5:` style prefix. Case does not matter, but stray characters do.
CIRCL hashlookup API — frequently asked questions
Is the CIRCL hashlookup API free?
Yes, free with no key or account. CIRCL runs it as a public service for the security community, and the main underlying dataset — NIST's NSRL — is US government work.
What does it mean if my hash is not found?
Almost nothing. The service indexes known catalogued software, and the overwhelming majority of files in the world are not in it — including every document you have ever written. A miss is not a signal of maliciousness.
Does a match mean the file is safe?
No. It means the file is a known, catalogued piece of software. NSRL contains plenty of software an organisation would rather not have installed, and living-off-the-land attacks deliberately use legitimate binaries. A match justifies lower priority, not a clean bill of health.
How do I check thousands of hashes at once?
Use the bulk POST endpoints, which accept a JSON array of hashes per algorithm. CIRCL also distributes an offline Bloom filter you can query locally, which is the right answer for processing whole disk images.
Tools that pair with this API
File Checksum Calculator
Calculate SHA-1, SHA-256 and SHA-512 checksums of any file in your browser. Copy each hash and compare against an expected value to verify a download is intact.
Hash Identifier
Paste a hash and find out what it probably is. Identifies MD5, SHA-1, SHA-256, NTLM, bcrypt, APR1 and more from length, character set and prefix.
Hash Comparer
Compare two hashes or strings side by side to check they match. Get a normalized equality verdict plus per-character diff highlighting, all offline in your browser.
CIRCL hashlookup is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.