Traceix Traceix API
Generate API Key

Overview #

The Traceix API lets you:

  • Upload a file to compute a canonical SHA-256 or classify immediately.
  • Search by SHA-256 for AI classification, file type, and model metadata.
  • Decrypt the encrypted training dataset for a result (quota-limited).
Base URL: https://ai.perkinsfund.org
Auth: send your key in the x-api-key header.
multipart/form-dataapplication/json

Authentication #

Include your key with every request:

x-api-key: <YOUR_API_KEY>

Quickstart #

cURL — upload & classify
curl -XPOST \
  -H "x-api-key: <YOUR_API_KEY>" \
  -F "file=@/path/to/file" \
  https://ai.perkinsfund.org/api/traceix/v1/upload
JavaScript — search

Endpoints #

POST /api/traceix/v1/upload

multipart/form-data

Upload a file to classify immediately (returns results.class and timing).

curl -XPOST \
  -H "x-api-key: <YOUR_API_KEY>" \
  -F "file=@/path/to/file" \
  https://ai.perkinsfund.org/api/traceix/v1/upload
Results (example)
{
  "class": "safe",
  "time_taken": 0.18
}
Full responses also include success, error, request_timestamp, and optional sponsor.

POST /api/traceix/v1/gethash

multipart/form-data

Upload a file and receive its SHA-256 hash.

curl -XPOST \
  -H "x-api-key: <YOUR_API_KEY>" \
  -F "file=@/path/to/file" \
  https://ai.perkinsfund.org/api/traceix/v1/gethash
Results (example)
{
  "file_hash": "ed369187681a62247e38d930320f1cd771756d0b7b67072d8ec655ef99e14aeb"
}

POST /api/traceix/v1/search

application/json

Search by SHA-256 to retrieve AI classification, file type, model metadata, and the encrypted training data blob.

Results (example)
{
  "classification": "safe",
  "file_type": "windows",
  "misc": {
    "accuracy": "91.64%",
    "analysis_time": 0.1037,
    "upload_timestamp": "2025-10-06 19:38:52",
    "version": "o1"
  },
  "sha256": "ed369187681a62247e38d930320f1cd771756d0b7b67072d8ec655ef99e14aeb",
  "training_data": "ENnVTlBeCJ7/.../my8"
}

POST /api/traceix/v1/decrypt

application/json

Decrypt the encrypted training dataset for a given hash (consumes decrypt quota).

curl -XPOST \
  -H "content-type: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  --data '{"sha256":"ed369187681a62247e38d930320f1cd771756d0b7b67072d8ec655ef99e14aeb","dataset":"ENnVTlBeCJ7/TPUo..."}' \
  https://ai.perkinsfund.org/api/traceix/v1/decrypt
Results (example)
{
  "AddressOfEntryPoint": 5952,
  "BaseOfCode": 4096,
  "Characteristics": 34,
  "ImportsNb": 33,
  "ImportsNbDLL": 7,
  "SectionsNb": 6,
  "SizeOfImage": 45056,
  "ResourcesNb": 7,
  "ResourcesMeanEntropy": 2.7989
  /* …more structured fields… */
}
If you receive a quota/allowance error, upgrade your plan or wait for reset.

On-Chain API (Free / No Key) #

Public endpoints powered by on-chain, immutable data. No API key required. Rate limited to 120 requests/min per IP.

Base URL: https://ai.perkinsfund.org
application/json
Responses may include sponsor fields acknowledging partners who fund free access.

POST /api/traceix/v1/ipfs/listall

no auth

List all available on-chain dataset entries with their IPFS cid and file sha256.

curl -XPOST https://ai.perkinsfund.org/api/traceix/v1/ipfs/listall
Results (example)
{
  "copyright": "(c) PCEF all rights reserved",
  "error": {},
  "request_timestamp": 1762267116.2708333,
  "results": [
    {"cid":"...","sha256":"..."},
    ...
  ],
  "sponsor": {
    "link": "...",
    "title": "..."
  },
  "success": true
}

POST /api/traceix/v1/ipfs/find

application/json • no auth

Look up an entry by file sha_hash (SHA-256). Returns cid and internal metadata when found.

curl -XPOST \
  -H "content-type: application/json" \
  --data '{"sha_hash":"10b740b968f59cb9d8a4167f72b1773f5e69269b1430a917a6e3e762d1a7526c"}' \
  https://ai.perkinsfund.org/api/traceix/v1/ipfs/find
Results (example)
{
  "data": {
    "file_data": {
      "file_size": "2251",
      "sha_hash": "10b740b968f59cb9d8a4167f72b1773f5e69269b1430a917a6e3e762d1a7526c"
    },
    "metadata": {
      "cid": "...",
      "rid": "..."
    }
  },
  "success": true
}
Not found (example)
{
  "data": {},
  "success": false
}

POST /api/traceix/v1/ipfs/search

application/json • no auth

Retrieve decrypted training data, classification, and metadata for a given IPFS cid.

Results (example)
{
  "copyright": "(c) PCEF all rights reserved",
  "error": {},
  "request_timestamp": 1762267143.519864,
  "results": {
    "decrypted_training_data": {
      ...
    },
    "metadata": {
      "model_information": {
        "model_accuracy": "91.64%",
        "model_version": "o1"
      },
      "payment_transaction": {
        "amount_paid": "...",
        "payment_tx": "...",
        "payment_tx_url": "https://solscan.io/tx/...",
        "thrt_price_at_payment": ...
      },
      "upload_information": {
        "file_sha_hash": "...",
        "license": "CC BY 4.0",
        "upload_timestamp": ...
      }
    },
    "model_classification_info": {
      "date_classified_on": ...,
      "identified_class": "...",
      "verdict_seconds": ...
    }
  },
  "sponsor": {
    "link": "...",
    "title": "..."
  },
  "success": true
}
Invalid CID (example)
{
  "copyright": "(c) PCEF all rights reserved",
  "error": { "error_message": "Invalid CID provided" },
  "request_timestamp": 1762267194.2231338,
  "results": null,
  "sponsor": {
    "link": "...",
    "title": "..."
  },
  "success": false
}

HTTP Status & Errors #

  • 200 with success: true — OK
  • 200 with success: false — logical error (e.g., not found, invalid input)
  • 401/403 — invalid or missing API key
  • 429 — rate limited or quota exceeded
  • 5xx — service issue; retry later