API Documentation

Integrate filehashes.io into your applications with our REST API.

Authentication

Anonymous requests are welcome for basic lookups. For tracking and higher rate limits, include your API key:

X-API-Key: fh_your_api_key_here

Or use Bearer authentication:

Authorization: Bearer fh_your_api_key_here

Base URL

https://api.filehashes.io

Endpoints

GET /health

Check API health and database connectivity.

curl https://api.filehashes.io/health

Response

        {
  "status": "healthy",
  "database": "connected",
  "latency": "1.2ms",
  "pool": {
    "total": 20,
    "idle": 18,
    "in_use": 2,
    "max": 20
  }
}
      

GET /v1/hash/:sha256

Look up a file by its SHA256 hash.

      curl https://api.filehashes.io/v1/hash/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
    

Response (found)

        {
  "found": true,
  "hash": {
    "id": 1,
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "md5": "d41d8cd98f00b204e9800998ecf8427e",
    "filename": "empty_file.txt",
    "file_size": 0,
    "times_seen": 47,
    "first_seen": "2025-01-01T00:00:00Z",
    "last_seen": "2026-01-04T12:00:00Z"
  }
}
      

Response (not found)

        {
  "found": false,
  "hash": null
}
      

POST /v1/hash

Submit a new file hash to the database.

      curl -X POST https://api.filehashes.io/v1/hash \
  -H "Content-Type: application/json" \
  -H "X-API-Key: fh_your_api_key" \
  -d '{
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "md5": "d41d8cd98f00b204e9800998ecf8427e",
    "filename": "empty_file.txt",
    "file_size": 0
  }'
    

Request Body

sha256 required: 64-character hexadecimal SHA256 hash
sha1 optional: 40-character hexadecimal SHA1 hash
md5 optional: 32-character hexadecimal MD5 hash
filename optional: Original filename (max 254 characters)
file_size optional: File size in bytes

Response (new hash)

        {
  "success": true,
  "new": true,
  "hash": {
    "id": 123,
    "sha256": "...",
    "times_seen": 1,
    "first_seen": "2026-01-04T12:00:00Z",
    "last_seen": "2026-01-04T12:00:00Z"
  }
}
      

Response (existing hash updated)

        {
  "success": true,
  "new": false,
  "hash": {
    "id": 123,
    "sha256": "...",
    "times_seen": 48,
    "first_seen": "2025-01-01T00:00:00Z",
    "last_seen": "2026-01-04T12:00:00Z"
  }
}
      

POST /v1/hash/bulk

Look up multiple hashes in a single request (max 100).

      curl -X POST https://api.filehashes.io/v1/hash/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "hashes": [
      "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a"
    ]
  }'
    

Response

        {
  "total": 2,
  "found": 1,
  "results": {
    "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855": {
      "found": true,
      "hash": { ... }
    },
    "a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a": {
      "found": false,
      "hash": null
    }
  }
}
      

GET /v1/stats

Get database statistics.

curl https://api.filehashes.io/v1/stats

Response

        {
  "total_hashes": 12345,
  "database_status": "connected"
}
      

Rate Limits

Tier	Lookups/day	Submissions/day
Anonymous	100	10
Free Account	1,000	100
Pro	10,000	1,000
Enterprise	Unlimited	Unlimited

Error Responses

400 Bad Request: Invalid hash format or missing required fields
401 Unauthorized: Invalid or missing API key (for protected endpoints)
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server-side error, please try again