perkins-fund-logo

AI Classifier API Docs

Scan Files 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 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.