How to use the File Reputation API

Learn how to utilize the Inception API to search across files and malware feeds

Note: This feature is in beta. Changes to this feature and its documentation may occur.

Last updated: 2/28/2023 (updated example output)

Table of Contents

  1. Overview
  2. Access the API
  3. Example output


The Inception File Reputation API enables organizations to leverage file data within Inception for data enrichment. With this API, you will be able to search across all files Inception has received from your organization, along with files received from the Stairwell global malware feeds.

Access the API

Use the following information to access the API:

  • HTTP REST endpoint:<FILE HASH>
  • Authentication: Pass X-ApiKey header with your Auth Token

Example with curl:


Note: You can use MD5, SHA-1, or SHA-256 for the file hash.

Example output

The following are example outputs, similar to the outputs you will see when a file is found or when a file is not found.

File found:

    "type": "file",
    "id": "f89d3d2177a4ad5a4995fd2bedaf13c6de2726e14f1367c21cdbb5c776aa1c7f",
    "links": {
        "self": "/api/v3/files/f89d3d2177a4ad5a4995fd2bedaf13c6de2726e14f1367c21cdbb5c776aa1c7f"
    "data": {
        "attributes": {
            "md5": "68927422419023003c40ecd438981af1",
            "sha1": "6303420a19756a69b436fd1e2902437ff0734613",
            "sha256": "f89d3d2177a4ad5a4995fd2bedaf13c6de2726e14f1367c21cdbb5c776aa1c7f",
            "size": 6113792,
            "creation_date": 1646274587,
            "names": [
            "meaningful_name": "C:\\Users\\ida\\go\\hello\\/hello.exe",
            "times_submitted": 1,
            "type_description": "EXE",
            "crowdsourced_yara_results": [
                    "rule_name": "Methodology_Codelang_Golang_BuildId_Catchall"
                    "rule_name": "Methodology_Codelang_Golang_Strings_PE"
                    "rule_name": "Methodology_Algorithm_SHA256_Constants"
                    "rule_name": "Methodology_PotentialCredentialHarvester"
            "occurrences": [
                    "environment": {
                      "id": "2FPYDD-8LP9XU-VYQAAC-VTRF29MT",
                      "name": "Ida Bear Sandbox"
                    "assets": [
                          "id": "AD64SQ-C3VABC-8HJN6L-LF2CR999",
                            "name": "WORKGROUP\\SW-MJW-CRD-1"
            "mal_eval_result": {
                "label": "onlinegames",
                "probability_bucket": "PROBABILITY_VERY_HIGH"
            "magic": "EXE",
            "imphash": "c7269d59926fa4252270f407e4dab043",
            "ssdeep": "98304:Q4xcDSb5mWNPEU8O/41EhETAN4EwKy+QJ:9yWBEjOd54+Q"

File not found:

"data": null,
"meta": null,
"links": {},
"error": {
"code": "NotFound",
"message": "no object found for identifier: sha256:\"e89d3d2177a4ad5a4995fd2bedaf13c6de2726e14f1367c21cdbb5c776aa1c7f\""