> For the complete documentation index, see [llms.txt](https://docs.perkinsfund.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perkinsfund.org/readme/traceix-endpoints/traceix.md).

# Traceix API

Traceix provides file upload + prediction, post-processing extractors (CAPA/EXIF/YARA), antivirus scanning and hash-based AV lookup, hash-based retrieval of prior results, and public IPFS dataset browsing/search all from a single API surface.

* [AI Prediction Upload](#ai-prediction-upload)
* [Check Upload Status](#check-upload-status)
* [CAPA Extraction](#capa-extraction)
* [EXIF Extraction](#exif-extraction)
* [YARA Rules](#yara-rule-creation)
* [Search CAPA by Hash](#search-capa-by-hash)
* [Search EXIF by Hash](#search-exif-by-hash)
* [Search YARA by Hash](#search-yara-by-hash)
* [AV File Scan](#av-file-scan)
* [AV Scan Status](#av-scan-status)
* [AV Hash Lookup](#av-hash-lookup)
* [List Public IPFS Datasets](#list-public-ipfs-datasets)
* [Get Public IPFS Dataset](#get-public-ipfs-dataset)
* [Search IPFS Dataset by Hash](#search-ipfs-dataset-by-hash)
* [SDKs](https://github.com/Perkins-Fund/Traceix-SDK)

### API BASE URL: `https://ai.perkinsfund.org`

***

### AI Prediction Upload

Endpoint: `/api/traceix/v1/upload`

Request type: POST

Data type: File

Headers: `X-Api-Key: API KEY`

#### Example request

```bash
curl -H "x-api-key: YOUR_API_KEY" \
     -F "file=@/path/to/file.exe" \
     https://ai.perkinsfund.org/api/traceix/v1/upload
```

#### Expected outputs

Success:

```json
{
  "success": true,
  "error": {},
  "request_timestamp": 1764610085.25132,
  "results": {
    "class": "safe",
    "time_taken": 0.46030490286648273,
  },
  "sponsor": {
    "link": "https://example.com/",
    "title": "Sponsor text"
  },
  "copyright": "(c) PCEF all rights reserved"
}
```

Unsuccessful:

```json
{
  "success": false,
  "error": {
    "error_message": "MESSAGE"
  },
  "results": {},
  "request_timestamp": 1764610085.25132
}
```

***

### Check Upload Status

Endpoint: `/api/v1/traceix/status`

Request type: POST

Data type: JSON

Headers: `X-Api-Key: API KEY`

**NOTE: A valid `uuid` from a prior upload is required.**

#### Example request

```bash
curl -X POST -H "x-api-key: YOUR_API_KEY" \
     -H "content-type: application/json" \
     --data '{"uuid": "YOUR_UUID_HERE"}' \
     https://ai.perkinsfund.org/api/v1/traceix/status
```

#### Expected outputs

Success:

**NOTE:** When the status is completed, related classification and metadata can be retrieved using the hash search and extraction endpoints below.

```json
{
  "success": true,
  "error": {},
  "results": {
    "uuid": "YOUR_UUID_HERE",
    "status": "queued"  // or "processing", "completed", "error"
  },
  "request_timestamp": 1764610085.25132
}
```

Unsuccessful (missing UUID, invalid UUID, etc.):

```json
{
  "success": false,
  "error": {
    "error_message": "You did not provide a UUID required by the endpoint"
  },
  "results": {}
}
```

***

### CAPA Extraction

Endpoint: `/api/traceix/v1/capa`

Request type: POST

Data type: File

Headers: `X-Api-Key: API KEY`

#### Example request

```bash
curl -H "x-api-key: YOUR_API_KEY" \
     -F "file=@/path/to/file.exe" \
     https://ai.perkinsfund.org/api/traceix/v1/capa
```

#### Expected outputs

Success:

```json
{
  "success": true,
  "error": {},
  "results": {
    "sha256": "FILE_SHA256",
    "capabilities": [
      {
        "name": "persistence via registry run key",
        "attack_id": "T1060",
      }
    ]
  }
}
```

Unsuccessful:

```json
{
  "success": false,
  "error": {
    "error_message": "MESSAGE"
  },
  "results": {}
}
```

***

### EXIF Extraction

Endpoint: `/api/traceix/v1/exif`

Request type: POST

Data type: File

Headers: `X-Api-Key: API KEY`

#### Example request

```bash
curl -H "x-api-key: YOUR_API_KEY" \
     -F "file=@/path/to/file.exe" \
     https://ai.perkinsfund.org/api/traceix/v1/exif
```

#### Expected outputs

Success:

```json
{
  "success": true,
  "error": {},
  "results": {
    "sha256": "FILE_SHA256",
    "metadata": {
      ...
    }
  }
}
```

Unsuccessful:

```json
{
  "success": false,
  "error": {
    "error_message": "MESSAGE"
  },
  "results": {}
}
```

***

### Yara Rule Creation

Endpoint: `/api/v1/traceix/ioc`

Request type: POST

Data type: File

Headers: `X-Api-Key: API KEY`

**NOTE: This endpoint requires a file upload (`multipart/form-data`).**

#### Example request

```bash
curl -H "x-api-key: YOUR_API_KEY" \
     -F "file=@/path/to/file.exe" \
     https://ai.perkinsfund.org/api/v1/traceix/ioc
```

#### Expected outputs

Success:

```json
{
  "data": {
    "yara_rule": "rule TraceixRuleGenerator_... { ... }"
  },
  "error": {},
  "success": true
}
```

Unsuccessful (JSON body instead of file):

```json
{
  "data": {},
  "error": {
    "msg": "This endpoint requires a file"
  },
  "success": false
}
```

### Search CAPA by Hash

Endpoint: `/api/traceix/v1/capa/search`

Request type: POST

Data type: JSON

Headers: `X-Api-Key: API KEY`

**NOTE: Uses the file SHA256 hash to retrieve previously extracted CAPA data.**

#### Example request

```bash
curl -X POST -H "x-api-key: YOUR_API_KEY" \
     -H "content-type: application/json" \
     --data '{"sha256": "FILE_SHA256"}' \
     https://ai.perkinsfund.org/api/traceix/v1/capa/search
```

#### Expected outputs

Success:

```json
{
  "success": true,
  "error": {},
  "results": {
    "sha256": "FILE_SHA256",
    "capabilities": [
      {
        "name": "persistence via registry run key",
        "attack_id": "T1060"
      }
    ]
  }
}
```

Unsuccessful:

```json
{
  "success": false,
  "error": {
    "error_message": "No matching record for provided SHA256"
  },
  "results": {}
}
```

***

### Search EXIF by Hash

Endpoint: `/api/traceix/v1/exif/search`

Request type: POST

Data type: JSON

Headers: `X-Api-Key: API KEY`

**NOTE: Uses the file SHA256 hash to retrieve previously extracted EXIF/metadata.**

#### Example request

```bash
curl -X POST -H "x-api-key: YOUR_API_KEY" \
     -H "content-type: application/json" \
     --data '{"sha256": "FILE_SHA256"}' \
     https://ai.perkinsfund.org/api/traceix/v1/exif/search
```

#### Expected outputs

Success:

```json
{
  "success": true,
  "error": {},
  "results": {
    "sha256": "FILE_SHA256",
    "metadata": {
      ...
    }
  }
}
```

Unsuccessful:

```json
{
  "success": false,
  "error": {
    "error_message": "No matching record for provided SHA256"
  },
  "results": {}
}
```

***

### Search YARA by Hash

Endpoint: `/api/v1/traceix/ioc/hash`

Request type: POST

Data type: JSON

Headers: `X-Api-Key: API KEY`

**NOTE: Uses the file SHA256 hash to retrieve a previously generated YARA rule.**

#### Example request

```bash
curl -X POST -H "x-api-key: YOUR_API_KEY" \
     -H "content-type: application/json" \
     --data '{"sha256":"FILE_SHA256"}' \
     https://ai.perkinsfund.org/api/v1/traceix/ioc/hash
```

#### Expected outputs

Success:

```json
{
  "data": {
    "rule": "rule TraceixRuleGenerator_... { ... }"
  },
  "error": {},
  "success": true
}
```

Unsuccessful (no rule for hash / bad hash):

```json
{
  "data": {},
  "error": {
    "msg": "No Yara rule from provided sha hash"
  },
  "success": false
}
```

***

### AV File Scan

Endpoint: `/api/v1/traceix/av/scan`

Request type: POST

Data type: File (`multipart/form-data`)

Headers: `X-Api-Key: API KEY`

**NOTE: Submitting a file returns one or more asynchronous scan jobs. Use the returned `uuid` values with the AV status endpoint below.**

#### Example request

```bash
curl -H "x-api-key: YOUR_API_KEY" \
     -F "file=@/path/to/file" \
     https://ai.perkinsfund.org/api/v1/traceix/av/scan
```

#### Expected outputs

Success:

```json
{
  "success": true,
  "error": {},
  "request_timestamp": 1774623901.183456,
  "results": [
    {
      "engine": "ENGINE_NAME",
      "status": "PENDING",
      "uuid": "UUID"
    },
    ...
  ]
}
```

Unsuccessful:

```json
{
  "success": false,
  "error": {
    "error_message": "MESSAGE"
  },
  "results": null
}
```

***

### AV Scan Status

Endpoint: `/api/v1/traceix/av/status`

Request type: POST

Data type: JSON

Headers: `X-Api-Key: API KEY`

**NOTE: Requires a valid `uuid` returned from `/api/v1/traceix/av/scan`.**

#### Example request

```bash
curl -X POST -H "x-api-key: YOUR_API_KEY" \
     --data '{"uuid":"SCAN_UUID"}' \
     https://ai.perkinsfund.org/api/v1/traceix/av/status
```

#### Expected outputs

Success:

```json
{
  "success": true,
  "error": {},
  "request_timestamp": 1774624038.659553,
  "results": {
    "engine": "ENGINE_NAME",
    "engine_type": "ENGINE_TYPE",
    "verdict": "VERDICT"
  }
}
```

Unsuccessful:

```json
{
  "success": false,
  "error": {
    "error_message": "MESSAGE"
  },
  "results": null
}
```

***

### AV Hash Lookup

Endpoint: `/api/v1/traceix/av/lookup`

Request type: POST

Data type: JSON

Headers: `X-Api-Key: API KEY`

**NOTE: Uses a file SHA256 hash to retrieve prior antivirus / reputation results when available.**

#### Example request

```bash
curl -X POST -H "x-api-key: YOUR_API_KEY" \
     --data '{"sha256":"FILE_SHA256"}' \
     https://ai.perkinsfund.org/api/v1/traceix/av/lookup
```

#### Expected outputs

Success:

```json
{
  "success": true,
  "error": {},
  "request_timestamp": 1774623825.928707,
  "results": [
    {
      "engine": "ENGINE_NAME",
      "engine_type": "ENGINE_TYPE",
      "file_hash": "FILE_SHA256",
      "verdict": "Safe" || "Malicious" || "Unknown" || "Failed"
    },
    ...
  ]
}
```

Unsuccessful:

```json
{
  "success": false,
  "error": {
    "error_message": "Invalid API key provided"
  },
  "request_timestamp": 1774623769.575932,
  "results": null
}
```

***

### List Public IPFS Datasets

Endpoint: `/api/traceix/v1/ipfs/listall`

Request type: POST

Data type: JSON (no body required)

Headers: *(API key not required, but accepted)*

#### Example request

```bash
curl -X POST \
     https://ai.perkinsfund.org/api/traceix/v1/ipfs/listall
```

#### Expected outputs

Success:

```json
{
  "copyright": "(c) PCEF all rights reserved",
  "error": {},
  "request_timestamp": 1762267116.2708333,
  "results": [
    { "cid": "...", "sha256": "..." },
    ...
  ],
  "sponsor": {
    "link": "...",
    "title": "..."
  },
  "success": true
}
```

Unsuccessful:

```json
{
  "copyright": "(c) PCEF all rights reserved",
  "error": {
    "error_message": "MESSAGE"
  },
  "request_timestamp": 1762267116.2708333,
  "results": [],
  "success": false
}
```

***

### Get Public IPFS Dataset

Endpoint: `/api/traceix/v1/ipfs/search`

Request type: POST

Data type: JSON

Headers: *(API key not required, but accepted)*

**NOTE: Requires the dataset `cid`.**

#### Example request

```bash
curl -X POST -H "content-type: application/json" \
     --data '{"cid": "bafybeigdyr..."}' \
     https://ai.perkinsfund.org/api/traceix/v1/ipfs/search
```

#### Expected outputs

Success:

```json
{
  "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
}
```

Unsuccessful:

```json
{
  "copyright": "(c) PCEF all rights reserved",
  "error": { "error_message": "Invalid CID provided" },
  "request_timestamp": 1762267194.2231338,
  "results": null,
  "sponsor": {
    "link": "...",
    "title": "..."
  },
  "success": false
}
```

***

### Search IPFS Dataset by Hash

Endpoint: `/api/traceix/v1/ipfs/find`

Request type: POST

Data type: JSON

Headers: *(API key not required, but accepted)*

**NOTE: Uses `sha_hash` to locate which public dataset a file appears in.**

#### Example request

```bash
curl -X POST -H "content-type: application/json" \
     --data '{"sha_hash": "FILE_SHA256"}' \
     https://ai.perkinsfund.org/api/traceix/v1/ipfs/find
```

#### Expected outputs

Success:

```json
{
  "data": {
    "file_data": {
      "file_size": "2251",
      "sha_hash": "10b740b968f59cb9d8a4167f72b1773f5e69269b1430a917a6e3e762d1a7526c"
    },
    "metadata": {
      "cid": "...",
      "rid": "..."
    }
  },
  "success": true
}
```

Unsuccessful:

```json
{
  "data": {},
  "success": false
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.perkinsfund.org/readme/traceix-endpoints/traceix.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.