> 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/cortex-agents.md).

# Cortex Agents API

Cortex Agents are lightweight "remote triage workers" that let your client check in, fetch its configuration, submit files for analysis, poll for results, and emit alerts — all under a consistent response envelope and strict ownership enforcement per API key.

* [Common Response Envelope](#common-response-envelope)
* [Agent Check-in](#agent-check-in)
* [Get Agent Metadata](#get-agent-metadata)
* [Run Agent](#run-agent)
* [Check Agent Run Status](#check-agent-run-status)
* [Submit Agent Alert](#submit-agent-alert)
* [Get Agent Alerts](#get-agent-alerts)
* [SDKs](#sdks)

### API Base URL

`https://ai.perkinsfund.org`

***

## Common Response Envelope

All endpoints return this top-level structure:

```json
{
  "error": {},
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768241023.740849,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": {},
  "success": true
}
```

On failure:

```json
{
  "error": {
    "error_message": "..."
  },
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768241028.700035,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": null,
  "success": false
}
```

### Authentication

All endpoints require:

* `X-Api-Key: YOUR_API_KEY`

### Ownership rule (important)

Where an endpoint accepts `agent_uuid`, the `agent_uuid` **must belong to the authenticated user (API key owner)**. Otherwise, the request fails (e.g., “Invalid agent UUID” / “Agent does not exist”).

***

## Agent Check-in

Endpoint: `/api/traceix/agent/checkin` Request type: `POST` Content type: JSON

Headers:

* `X-Api-Key: YOUR_API_KEY`
* `content-type: application/json`

Body:

* `agent_uuid`: string

### Example request

```bash
curl -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  --data '{"agent_uuid":"AGENT_UUID"}' \
  https://ai.perkinsfund.org/api/traceix/agent/checkin
```

### Expected outputs

Success:

```json
{
  "error": {},
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768240753.374693,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": { "ok": true },
  "success": true
}
```

Failure (invalid agent UUID):

```json
{
  "error": { "error_message": "Invalid agent UUID" },
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768240797.701423,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": null,
  "success": false
}
```

***

## Get Agent Metadata

Endpoint: `/api/traceix/agent/metadata` Request type: `POST` Content type: JSON

Headers:

* `X-Api-Key: YOUR_API_KEY`
* `content-type: application/json`

Body:

* `agent_uuid`: string

### Example request

```bash
curl -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  --data '{"agent_uuid":"AGENT_UUID"}' \
  https://ai.perkinsfund.org/api/traceix/agent/metadata
```

### Expected outputs

Success:

```json
{
  "error": {},
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768241023.740849,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": {
    "agent_config": {
      "accepted_file_type": "windows",
      "agent_features": ["classification", "exif"],
      "agent_uuid": "agnt-...",
      "max_file_size": 3145728,
      "requested_delivery_style": "raw"
    },
    "agent_metadata": {
      "agent_created_at": "2026-01-12T16:27:11.903000+00:00",
      "agent_name": "Traceix Windows Fast Triage",
      "agent_stats": { "processed_files": 1 },
      "agent_tags": ["triage", "windows", "soc"]
    }
  },
  "success": true
}
```

Failure (not owned / not accessible / doesn’t exist):

```json
{
  "error": { "error_message": "Agent does not exist" },
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768241028.700035,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": null,
  "success": false
}
```

***

## Run Agent

Endpoint: `/api/traceix/agent/run` Request type: `POST` Content type: `multipart/form-data`

Headers:

* `X-Api-Key: YOUR_API_KEY`
* `X-Agent-Id: AGENT_UUID`

Body:

* `file`: the file to submit (multipart form)

> **NOTE:** This endpoint queues an analysis job and returns a `uuid` you will poll using `/api/traceix/agent/status`.

### Example request

```bash
curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-agent-id: AGENT_UUID" \
  -F "file=@/path/to/file.exe" \
  https://ai.perkinsfund.org/api/traceix/agent/run
```

### Expected outputs

Success (queued):

```json
{
  "error": {},
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768241074.539515,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": {
    "status": "PENDING",
    "uuid": "67fa2864-5c58-4533-b626-3da9dd48bb76"
  },
  "success": true
}
```

Failure (agent does not exist / not accessible):

```json
{
  "error": { "error_message": "Agent does not exist" },
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768241082.298161,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": null,
  "success": false
}
```

***

## Check Agent Run Status

Endpoint: `/api/traceix/agent/status` Request type: `POST` Content type: JSON

Headers:

* `X-Api-Key: YOUR_API_KEY`
* `content-type: application/json`

Body:

* `uuid`: string (the job UUID returned from `/api/traceix/agent/run`)
* `agent_uuid`: string (the agent UUID used to launch the job)

> **NOTE:** You must provide **both** `uuid` and `agent_uuid`.

### Example request

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

### Expected outputs

Success can return **either** a pending status **or** completed results.

Success (pending):

```json
{
  "error": {},
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768241148.871836,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": {
    "status": "PENDING",
    "uuid": "67fa2864-5c58-4533-b626-3da9dd48bb76"
  },
  "success": true
}
```

Success (completed example):

```json
{
  "error": {},
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768241143.9729,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": {
    "classification": "safe",
    "exif": {
      "FileDescription": "Windows Calculator"
    }
  },
  "success": true
}
```

Failure example:

```json
{
  "error": { "error_message": "Invalid agent UUID" },
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768241401.4666727,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": null,
  "success": false
}
```

***

## Submit Agent Alert

Endpoint: `/api/traceix/agent/alert` Request type: `POST` Content type: JSON

Headers:

* `X-Api-Key: YOUR_API_KEY`
* `content-type: application/json`

Body (required):

* `agent_uuid`: string
* `client_id`: string
* `classification`: string (example: `safe`, `malicious`, etc.)
* `file_path`: string
* `sha256_hash`: string

Body (optional / nullable):

* `capa`: array or null
* `exif`: object or null
* `yara`: string or null

### Example request

```bash
curl -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  --data '{
    "agent_uuid":"AGENT_UUID",
    "client_id":"test_id",
    "classification":"safe",
    "file_path":"C:\\Windows\\System32\\calc.exe",
    "sha256_hash":"ed369187681a62247e38d930320f1cd771756d0b7b67072d8ec655ef99e14aeb"
  }' \
  https://ai.perkinsfund.org/api/traceix/agent/alert
```

### Expected outputs

Success:

```json
{
  "error": {},
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768240926.097389,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": { "ok": true },
  "success": true
}
```

Failure (invalid agent UUID):

```json
{
  "error": { "error_message": "Invalid agent UUID" },
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768240895.260689,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": null,
  "success": false
}
```

***

## Get Agent Alerts

Endpoint: `/api/traceix/agent/alerts/get` Request type: `POST` Content type: JSON

Headers:

* `X-Api-Key: YOUR_API_KEY`
* `content-type: application/json`

Body:

* `agent_uuid`: string

### Example request

```bash
curl -X POST \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  --data '{"agent_uuid":"AGENT_UUID"}' \
  https://ai.perkinsfund.org/api/traceix/agent/alerts/get
```

### Expected outputs

Success (example shape):

```json
{
  "error": {},
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768240989.672061,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": [
    {
      "agent_uuid": "agnt-...",
      "alert_id": "alrt_...",
      "alert_timestamp": "2026-01-12T18:02:06.062701+00:00",
      "classification": "safe",
      "client_id": "test_id",
      "event_id": "evt_...",
      "file_path": "C:\\Windows\\System32\\calc.exe",
      "sha256_hash": "ed36...",
      "is_reviewed": false,
      "last_check_in": null,
      "capabilities": null,
      "exif_data": null,
      "yara_rule": null
    }
  ],
  "success": true
}
```

Failure (invalid agent UUID):

```json
{
  "error": { "error_message": "Invalid agent UUID" },
  "request_metadata": {
    "request_id": "req_...",
    "request_timestamp": 1768241001.276291,
    "schema_version": "traceix.agent_output.v1"
  },
  "results": null,
  "success": false
}
```

***

## SDKs

* GitHub: `https://github.com/Perkins-Fund/Traceix-SDK`
* More languages: coming soon…


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.