Submit Hash

The Submit Hash endpoint lets you quickly check if CyberShield has already scanned a file before.
If the hash exists in the database, the API instantly returns a cached report—no upload needed.

Use this endpoint for fast lookups, CI/CD workflows, large file screening, or pre-processing pipelines.

---

Endpoint Summary

Method	Endpoint
POST	/scan/hash

Parameter	Type	Required	Description
hash	String	Yes	SHA-256 hash of the file.
requestId	String	No	Optional ID for tracking or internal correlation.

---

Request Format

Headers

Header	Value
Authorization	Bearer YOUR_API_KEY
Content-Type	application/json

Body Example

{
  "hash": "97c3f1a4b67e893fe2e7db4c279c82f7a002906c6a851d9f96e23c4c5dc7b901",
  "requestId": "lookup-001"
}

---

Example Requests

JavaScript (Node.js)

import axios from "axios";

axios.post(
  "https://api.cybershield.com/scan/hash",
  {
    hash: "97c3f1a4b67e893fe2e7db4c279c82f7a002906c6a851d9f96e23c4c5dc7b901"
  },
  {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    }
  }
)
.then(res => console.log("Lookup Result:", res.data))
.catch(err => console.error("Error:", err.response?.data || err.message));

Python

import requests

url = "https://api.cybershield.com/scan/hash"
payload = {
    "hash": "97c3f1a4b67e893fe2e7db4c279c82f7a002906c6a851d9f96e23c4c5dc7b901"
}

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

---

Example Responses

If a result exists (instant return)

{
  "status": "completed",
  "scanId": "ab4d28f9-3341-4c89-83b0-4458b9c61afd",
  "cached": true,
  "threatLevel": "low",
  "message": "Cached scan report available."
}

If a new scan is required

{
  "status": "processing",
  "scanId": "3a92fa8e-8c9e-4b6f-9b83-2fafc982d4db",
  "cached": false,
  "message": "Hash not found. File needs to be uploaded for a full scan."
}

---

Common Response Fields

Field	Description
scanId	Identifier for retrieving full report using Get Report.
cached	Indicates whether the result already existed.
status	completed, processing, or failed.
message	More information about the lookup result.

---

Error Handling

Error Code	Meaning	Fix
400 Bad Request	Invalid or missing hash	Provide a valid SHA-256 hash.
401 Unauthorized	Wrong or missing API key	Verify your API key.
404 Not Found	Hash exists but result unavailable	Upload file using Scan File.
429 Too Many Requests	Rate limit exceeded	Retry later or implement backoff.

---

Next Step

To fetch a complete scan analysis:

➡ Get Report