Cortex Agents

NOTE: Some features may not be publicly released yet.

API Base URL

https://ai.perkinsfund.org

Common Response Envelope

All endpoints return this top-level structure:

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

On failure:

{
  "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

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:

{
  "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):

{
  "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

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:

{
  "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):

{
  "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

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):

{
  "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):

{
  "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

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):

{
  "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):

{
  "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:

{
  "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

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:

{
  "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):

{
  "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

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):

{
  "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):

{
  "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…

PreviousTraceix NextYara Rule Playground

Last updated 9 days ago

Was this helpful?

Good afternoon

hashtagAPI Base URL

hashtagCommon Response Envelope

hashtagAuthentication

hashtagOwnership rule (important)

hashtagAgent Check-in

hashtagExample request

hashtagExpected outputs

hashtagGet Agent Metadata

hashtagExample request

hashtagExpected outputs

hashtagRun Agent

hashtagExample request

hashtagExpected outputs

hashtagCheck Agent Run Status

hashtagExample request

hashtagExpected outputs

hashtagSubmit Agent Alert

hashtagExample request

hashtagExpected outputs

hashtagGet Agent Alerts

hashtagExample request

hashtagExpected outputs

hashtagSDKs

API Base URL

Common Response Envelope

Authentication

Ownership rule (important)

Agent Check-in

Example request

Expected outputs

Get Agent Metadata

Example request

Expected outputs

Run Agent

Example request

Expected outputs

Check Agent Run Status

Example request

Expected outputs

Submit Agent Alert

Example request

Expected outputs

Get Agent Alerts

Example request

Expected outputs

SDKs