Skip to content

API: Agents

This section explains how to list, inspect, and update agents via the API.

List Agents

Retrieve all agents, or filter by active/inactive state.

All agents:

1
2
GET /api/v1/agents HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Active agents only:

1
2
GET /api/v1/agents/active HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Inactive agents only:

1
2
GET /api/v1/agents/inactive HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Get Agent Details

Fetch full information for a specific agent.

1
2
GET /api/v1/agents/{AGENT_GUID} HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Mark Agent as Inactive

Move a connected agent to the inactive list.

1
2
PUT /api/v1/agents/{AGENT_GUID}/inactive HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Update Agent

You can add or update metadata and custom properties for an agent or modify other agent aspects.

Update metadata

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
PUT /api/v1/agents/{AGENT_GUID}/metadata HTTP/1.1
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "username": "exampleUser",
  "proc": "exampleProcess",
  "pid": 2222,
  "workingDir": "exampleDir",
  "os": 2,
  "os_major": 2,
  "os_minor": 2,
  "ips": "exampleIP",
  "hostname": "exampleHost",
  "customProperties": {
    "key": "value"
  }
}

Clear agent command queue

1
2
POST /api/v1/agents/{AGENT_GUID}/commands/queue/clear HTTP/1.1
Authorization: Bearer {JWT_TOKEN}

Info

Replace all example values with the actual data for the agent you are updating.