perkins-fund-logo

API Docs

Scan Files Now Build YARA Rules Donate Now

BASE URL: https://ai.perkinsfund.org

/api/predict

ENDPOINT: /api/predict

REQUEST TYPE: POST

DATA TYPE: File

NOTE: The AI currently only classifies ELF and Windows PE executable file formats. Others will be "unknown".

Code Snippets 

curl -F"filename=@/path/to/file" https://ai.perkinsfund.org/api/predict
Expected Outputs 
File classified:
  "results": {
    "class": "safe",
    "created_at": 1743103981.5979574,
    "file_hash": "ed369187681a62247e38d930320f1cd771756d0b7b67072d8ec655ef99e14aeb",
    "time_taken": 0.37021786579862237
  },
Encountered an error:
{
   "error": {
      "error_message": "The message"
   },
}

/api/latest

ENDPOINT: /api/latest

METHOD: POST

DATA TYPE: JSON

NOTE: Returns the latest 50 scans

Code Snippets 

curl -X POST https://ai.perkinsfund.org/api/latest
Expected Outputs 
Latest data grabbed successfully:
[
    {
      "class": "unknown",
      "created_at": 1743103290.500192,
      "error": {},
      "file_hash": "008632ed4a903dbc95d7a0d042d77df9bf651f10a26a8d4557eb9d2533193ad1",
      "time_taken": 0.0004930980503559113
    },
    {
      "class": "unknown",
      "created_at": 1743099196.4861066,
      "error": {},
      "file_hash": "f5f5ac913edc3fa09bc71ff99d6b84fa63c5987f9713fdb1d55f590ac283b263",
      "time_taken": 0.000505556003190577
    }
]
Encountered an error:
{
  "error_message": {"error_message": "..."},
  "results": []
}

/api/search

ENDPOINT: /api/search

REQUEST TYPE: POST

DATA TYPE: JSON

HEADERS: X-Api-Key (required)

Get API Key
Code Snippets 
curl -XPOST -H "x-api-key: USER KEY" -H "content-type: application/json" --data '{"sha256":"USER SHA256 HASH"}' https://ai.perkinsfund.org/api/search
Expected Outputs 
Successful response:
  "results": {
    "class": "safe",
    "created_at": 1742832170.874544,
    "error": {},
    "file_hash": "975d2ab9067a1b21a46ce9d87e6ab589636d128fcba4f49e53392815ebc72d77",
    "time_taken": 0.7284463751129806
  }
Invalid or missing hash:
{
  "error": {
    "error_message": "SHA256 hash did not pass heuristics check, is it a hash?"
  }
}
Invalid API key:
{
  "error": {
    "error_message": "invalid API key supplied"
  }
}

/api/yara/build

ENDPOINT: /api/yara/build

REQUEST TYPE: POST

DATA TYPE: JSON

HEADERS: Content-Type: application/json

DESCRIPTION: Compiles the provided YARA rule and returns whether the rule is valid.

Code Snippets 
curl -X POST -H "Content-Type: application/json" -d '{"rule": "rule dummy { condition: true }"}' https://ai.perkinsfund.org/api/yara/build
Expected Outputs 
Successful response:
   "results": {
    "success": "YARA rule compiled successfully"
  },
Unsuccessful Build
  "error": {
    "error_message": "YARA rule syntax error: line 1: syntax error, unexpected identifier, expecting  <condition>"
  }

/api/yara/test

ENDPOINT: /api/yara/test

REQUEST TYPE: POST

DATA TYPE: multipart/form-data

DESCRIPTION: Tests a YARA rule against a specific uploaded file.

Code Snippets 
curl -F "[email protected]" -F "[email protected]" https://ai.perkinsfund.org/api/yara/test
Expected Outputs 
Successful response:
  "results": [
    {
      "matched_strings": [],
      "rule": "test"
    }
  ],
Unsuccessful Build
  "error": {
    "error_message": "YARA rule syntax error: line 2: syntax error, unexpected identifier, expecting <condition>"
  }
No results found

                      "error": {
    "error_message": "No matches found using YARA rule"
  },

/api/yara/scan

ENDPOINT: /api/yara/scan

REQUEST TYPE: POST

DATA TYPE: JSON

HEADERS: Content-Type: application/json, x-file-type (required, "malware" or "benign")

DESCRIPTION: Runs a YARA rule against internal known files of a specified type.

Code Snippets 
curl -X POST -H "Content-Type: application/json" -H "x-file-type: benign" -d '{"rule": "rule dummy { condition: true }"}' https://ai.perkinsfund.org/api/yara/scan
Expected Outputs 
Successful response:
  "results": [
    "4c2765686236234db7693c622373c44cda172536f0066820fed70a1ca86519dd",
    "6312581860b1873dedeb8c2cd916fb27baa061f62b0cde44167f4cefebe0628a",
    "862588b2f549abd71bc219dab6e3627ec792cefd2ee6ff0857ccc4fd2e552cc6",
    "8109d3330a58d934fc0bf989b06ca612a317e2085f6477a8b8f8296b452d1ed0",
    "a4940a198a5d2ef2d68e3d643058ed1ee123ce3f8ef6e9e923360d80f81b684d",
    "52f95f4a253c431221852fa0e0fb9ab94752fdee597750949460c74242887b09",
    "d1b807df597b47d162d7235d8389e366d24a2cc2e379f48bebbe7855f420e660",
    ... ]    
Unsuccessful Build
  "error": {
    "error_message": "YARA rule syntax error: line 2: syntax error, unexpected identifier, expecting <condition>"
  }
No results found

                        "error": {
    "error_message": "No matches found for YARA rule in 50 samples"
  },

API Response Format

All endpoints return a standardized JSON response structure. Here's an example of a successful scan response:

{
  "copyright": "(c) PCEF all rights reserved", (only shown if no API key is passed)
  "error": {
    "error_message": ... (if an error)
  },
  "request_timestamp": 1743098585.390719,
  "results": {
    ... || null
  },
  "sponsor": { (if invalid or no API key provided in request)
    "link": ...,
    "title": ...
  },
  "success": true || false (if an error)
}

Field Descriptions:

Note: If the request includes a valid API key, the sponsor field will be omitted from the response.