Agents API

The Agents API provides endpoints for managing endpoint agents deployed across your organization. You can list agents, view their details, update configurations, execute response actions, and manage isolation states.

Endpoints Overview

Method	Endpoint	Description
GET	`/api/v1/agents`	List all agents
GET	`/api/v1/agents/:id`	Get agent details
PATCH	`/api/v1/agents/:id`	Update agent
DELETE	`/api/v1/agents/:id`	Delete agent
POST	`/api/v1/agents/:id/isolate`	Isolate agent
POST	`/api/v1/agents/:id/unisolate`	Remove isolation
GET	`/api/v1/agents/:id/isolation`	Get isolation status
POST	`/api/v1/agents/:id/restart`	Restart agent
PUT	`/api/v1/agents/:id/config`	Update agent config
GET	`/api/v1/agents/:id/events`	Get agent events
GET	`/api/v1/agents/:id/processes`	Get process tree

List Agents

Retrieve a list of all agents in your organization.

Endpoint: GET /api/v1/agents Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `online`, `offline`, `isolated`
`os_type`	string	Filter by OS: `windows`, `linux`, `macos`
`hostname`	string	Filter by hostname (partial match)
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 50, max: 200)

Example Request:

curl -X GET "https://api.tamandua.io/api/v1/agents?status=online&os_type=windows" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "hostname": "WORKSTATION-01",
      "os_type": "windows",
      "os_version": "Windows 10 Pro 22H2",
      "agent_version": "1.5.0",
      "status": "online",
      "isolated": false,
      "isolation_status": null,
      "last_seen": "2024-01-15T14:30:00Z",
      "created_at": "2024-01-01T09:00:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "hostname": "SERVER-DC01",
      "os_type": "windows",
      "os_version": "Windows Server 2022",
      "agent_version": "1.5.0",
      "status": "online",
      "isolated": false,
      "isolation_status": null,
      "last_seen": "2024-01-15T14:29:55Z",
      "created_at": "2023-12-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 152,
    "total_pages": 4
  }
}

Get Agent Details

Retrieve detailed information about a specific agent, including health metrics, recent events, and configuration.

Endpoint: GET /api/v1/agents/:id Example Request:

curl -X GET "https://api.tamandua.io/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "hostname": "WORKSTATION-01",
    "os_type": "windows",
    "os_version": "Windows 10 Pro 22H2",
    "agent_version": "1.5.0",
    "status": "online",
    "isolated": false,
    "isolation_status": null,
    "last_seen": "2024-01-15T14:30:00Z",
    "created_at": "2024-01-01T09:00:00Z",
    "health": {
      "cpu_usage": 15.5,
      "memory_usage": 62.3,
      "disk_usage": 45.0,
      "cpu_history": [12.0, 14.5, 15.0, 15.5],
      "memory_history": [60.0, 61.0, 62.0, 62.3],
      "uptime_seconds": 345600
    },
    "collectors": [
      {
        "name": "process",
        "status": "running",
        "events_collected": 15420,
        "last_event_at": "2024-01-15T14:29:58Z",
        "error_message": null
      },
      {
        "name": "file",
        "status": "running",
        "events_collected": 8230,
        "last_event_at": "2024-01-15T14:29:55Z",
        "error_message": null
      },
      {
        "name": "network",
        "status": "running",
        "events_collected": 42150,
        "last_event_at": "2024-01-15T14:29:59Z",
        "error_message": null
      }
    ],
    "events": [
      {
        "id": "evt-001",
        "agent_id": "550e8400-e29b-41d4-a716-446655440000",
        "event_type": "process_create",
        "severity": "info",
        "timestamp": "2024-01-15T14:29:58Z",
        "payload": {
          "name": "chrome.exe",
          "pid": 1234,
          "ppid": 5678
        }
      }
    ],
    "alerts": [
      {
        "id": "alert-001",
        "title": "Suspicious PowerShell execution",
        "severity": "high",
        "status": "open",
        "created_at": "2024-01-15T10:15:00Z"
      }
    ],
    "config": {
      "collectors": {
        "process": true,
        "file": true,
        "network": true,
        "dns": true,
        "registry": true
      },
      "performance_profile": "balanced"
    }
  }
}

Update Agent

Update agent settings such as tags, groups, or custom metadata.

Endpoint: PATCH /api/v1/agents/:id Request Body:

Field	Type	Description
`tags`	array	Custom tags for the agent
`group`	string	Agent group name
`notes`	string	Admin notes

Example Request:

curl -X PATCH "https://api.tamandua.io/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["production", "critical"],
    "group": "domain-controllers",
    "notes": "Primary DC for EMEA region"
  }'

Example Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "hostname": "SERVER-DC01",
    "tags": ["production", "critical"],
    "group": "domain-controllers",
    "notes": "Primary DC for EMEA region",
    "status": "online",
    "last_seen": "2024-01-15T14:30:00Z"
  }
}

Delete Agent

Remove an agent from the system. This does not uninstall the agent software.

Endpoint: DELETE /api/v1/agents/:id Example Request:

curl -X DELETE "https://api.tamandua.io/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer tam_live_xxxxx"

Response: 204 No Content

Isolate Agent

Network-isolate an agent to contain a potential threat. The agent will only communicate with the Tamandua server and optionally specified allowed IPs.

Endpoint: POST /api/v1/agents/:id/isolate Request Body:

Field	Type	Description
`allowed_ips`	array	IP addresses/CIDRs to allow during isolation

Example Request:

curl -X POST "https://api.tamandua.io/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/isolate" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_ips": ["10.0.0.1", "192.168.1.0/24"]
  }'

Example Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "hostname": "WORKSTATION-01",
    "status": "isolated",
    "isolated": true,
    "isolation_status": {
      "state": "enabled",
      "enabled_at": "2024-01-15T14:35:00Z",
      "allowed_ips": ["10.0.0.1", "192.168.1.0/24"]
    }
  },
  "message": "Agent isolation command executed",
  "isolation_status": "enabled"
}

Remove Isolation

Remove network isolation from an agent, restoring normal network connectivity.

Endpoint: POST /api/v1/agents/:id/unisolate Example Request:

curl -X POST "https://api.tamandua.io/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/unisolate" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "hostname": "WORKSTATION-01",
    "status": "online",
    "isolated": false,
    "isolation_status": null
  },
  "message": "Agent de-isolation command executed",
  "isolation_status": "disabled"
}

Get Isolation Status

Get detailed information about the agent's isolation state.

Endpoint: GET /api/v1/agents/:id/isolation Example Request:

curl -X GET "https://api.tamandua.io/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/isolation" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "success": true,
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "isolation_status": {
    "state": "enabled",
    "enabled_at": "2024-01-15T14:35:00Z",
    "enabled_by": "admin@example.com",
    "allowed_ips": ["10.0.0.1", "192.168.1.0/24"],
    "rules_applied": 5,
    "connectivity": {
      "server": "connected",
      "internet": "blocked"
    }
  }
}

Restart Agent

Send a restart command to the agent. Useful for applying configuration changes or recovering from errors.

Endpoint: POST /api/v1/agents/:id/restart Example Request:

curl -X POST "https://api.tamandua.io/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/restart" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "success": true,
  "message": "Restart command sent to agent"
}

Error Response (Agent Offline):

{
  "success": false,
  "error": "Agent is not connected"
}

Update Agent Configuration

Push configuration updates to an agent in real-time.

Endpoint: PUT /api/v1/agents/:id/config Request Body:

Field	Type	Description
`config`	object	Configuration settings to update

Example Request:

curl -X PUT "https://api.tamandua.io/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/config" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "collectors": {
        "process": true,
        "file": true,
        "network": true,
        "dns": true,
        "registry": false
      },
      "performance_profile": "aggressive",
      "upload_interval_ms": 5000
    }
  }'

Example Response:

{
  "success": true,
  "message": "Configuration update sent to agent"
}

Get Agent Events

Retrieve telemetry events from a specific agent with filtering options.

Endpoint: GET /api/v1/agents/:id/events Query Parameters:

Parameter	Type	Description
`event_type`	string	Filter by event type
`severity`	string	Filter by severity
`from`	string	Start timestamp (ISO 8601)
`to`	string	End timestamp (ISO 8601)
`limit`	integer	Max results (default: 100)
`offset`	integer	Skip results (default: 0)

Example Request:

curl -X GET "https://api.tamandua.io/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/events?event_type=process_create&limit=50" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "data": [
    {
      "id": "evt-001",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "event_type": "process_create",
      "severity": "info",
      "timestamp": "2024-01-15T14:29:58Z",
      "payload": {
        "name": "powershell.exe",
        "pid": 1234,
        "ppid": 5678,
        "path": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
        "cmdline": "powershell.exe -ExecutionPolicy Bypass -File script.ps1",
        "user": "DOMAIN\\user"
      }
    }
  ],
  "meta": {
    "total": 1520,
    "limit": 50,
    "offset": 0
  }
}

Get Process Tree

Retrieve the current process tree from an agent.

Endpoint: GET /api/v1/agents/:id/processes Query Parameters:

Parameter	Type	Description
`page`	integer	Page number for flat list
`per_page`	integer	Items per page (max: 500)

Example Request (Tree):

curl -X GET "https://api.tamandua.io/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/processes" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "data": [
    {
      "pid": 4,
      "ppid": 0,
      "name": "System",
      "path": "",
      "cmdline": "",
      "user": "SYSTEM",
      "startTime": "2024-01-01T00:00:00Z",
      "isElevated": true,
      "isSigned": true,
      "signer": "Microsoft Windows",
      "childCount": 125,
      "children": [
        {
          "pid": 756,
          "ppid": 4,
          "name": "smss.exe",
          "path": "C:\\Windows\\System32\\smss.exe",
          "childCount": 2,
          "children": []
        }
      ]
    }
  ],
  "meta": {
    "truncated": false
  }
}

Example Request (Paginated Flat List):

curl -X GET "https://api.tamandua.io/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/processes?page=1&per_page=100" \
  -H "Authorization: Bearer tam_live_xxxxx"

Get Process Children

Retrieve child processes for a specific process.

Endpoint: GET /api/v1/agents/:id/processes/:pid/children Example Request:

curl -X GET "https://api.tamandua.io/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/processes/4/children?limit=50" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "data": [
    {
      "pid": 756,
      "ppid": 4,
      "name": "smss.exe",
      "path": "C:\\Windows\\System32\\smss.exe",
      "isSigned": true,
      "signer": "Microsoft Windows"
    }
  ],
  "meta": {
    "total": 125,
    "parent_pid": 4
  }
}

Get Process Ancestors

Retrieve the ancestor chain (parent, grandparent, etc.) for a process.

Endpoint: GET /api/v1/agents/:id/processes/:pid/ancestors Example Request:

curl -X GET "https://api.tamandua.io/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/processes/1234/ancestors" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "data": [
    {
      "pid": 1234,
      "ppid": 5678,
      "name": "powershell.exe",
      "path": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
    },
    {
      "pid": 5678,
      "ppid": 9012,
      "name": "explorer.exe",
      "path": "C:\\Windows\\explorer.exe"
    },
    {
      "pid": 9012,
      "ppid": 4,
      "name": "userinit.exe",
      "path": "C:\\Windows\\System32\\userinit.exe"
    }
  ],
  "meta": {
    "target_pid": 1234,
    "depth": 3
  }
}

Error Responses

Agent Not Found

{
  "error": "Agent not found"
}

HTTP Status: 404

Agent Not Connected

{
  "success": false,
  "error": "Agent is not connected"
}

HTTP Status: 404

Command Failed

{
  "success": false,
  "error": "Command execution failed: timeout"
}

HTTP Status: 400

Process Tree Timeout

{
  "error": "timeout",
  "message": "Process tree loading timed out. Use paginated endpoints for large process lists."
}

HTTP Status: 504