List Agents
Retrieve all registered agents in your organization.
Your API key (sk_live_...)
curl -H "X-API-Key: sk_live_your_key_here" \
https://api.turen.dev/api/v1/registered-agents
Query Parameters
| Parameter | Type | Default | Description |
|---|
limit | number | 50 | Number of agents to return |
offset | number | 0 | Pagination offset |
Response
{
"agents": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"client_id": "a1b2c3d4e5f67890",
"machine_id": "IOPlatformUUID-xxx",
"generation": 1,
"secret_prefix": "as_live_abc",
"registration_key_id": "key-uuid",
"registration_key_name": "Engineering Team",
"status": "active",
"hostname": "johns-macbook-pro",
"os": "darwin",
"arch": "arm64",
"version": "1.2.0",
"username": "john",
"clone_detected": false,
"registered_at": "2026-01-15T08:00:00Z",
"last_seen_at": "2026-02-17T10:30:00Z"
}
],
"pagination": {
"limit": 50,
"offset": 0,
"total": 12,
"has_more": false
}
}
Response Fields
| Field | Type | Description |
|---|
id | string | Unique agent identifier |
client_id | string | Machine fingerprint-derived ID |
machine_id | string | Platform-specific machine identifier |
generation | number | Agent generation counter |
secret_prefix | string | Prefix of the agent’s secret (for identification) |
registration_key_id | string | ID of the registration key used |
registration_key_name | string | Name of the registration key used |
status | string | active, suspended, or deleted |
hostname | string | Machine hostname |
os | string | Operating system |
arch | string | CPU architecture |
version | string | Installed agent version |
username | string | OS username running the agent |
clone_detected | boolean | Whether clone/VM duplication was detected |
clone_reason | string | Reason for clone detection (if applicable) |
registered_at | string | ISO 8601 timestamp of registration |
last_seen_at | string | ISO 8601 timestamp of last check-in |
Get Agent
Retrieve a single agent by ID.
curl -H "X-API-Key: sk_live_your_key_here" \
https://api.turen.dev/api/v1/registered-agents/{id}
Update Agent Status
Suspend or reactivate an agent.
curl -X PUT \
-H "X-API-Key: sk_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"status": "suspended", "reason": "Under investigation"}' \
https://api.turen.dev/api/v1/registered-agents/{id}/status
Request Body
| Field | Type | Required | Description |
|---|
status | string | Yes | active or suspended |
reason | string | No | Reason for the status change |
204 No Content on success.
Delete Agent
Remove an agent from your organization.
curl -X DELETE \
-H "X-API-Key: sk_live_your_key_here" \
https://api.turen.dev/api/v1/registered-agents/{id}
Query Parameters
| Parameter | Type | Default | Description |
|---|
hard | boolean | false | Permanently delete (vs soft delete) |
reason | string | - | Reason for deletion |
Hard deletion is permanent. The machine will need a new registration key to rejoin.
