> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turen.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> List and manage registered agents

## List Agents

Retrieve all registered agents in your organization.

<ParamField header="X-API-Key" type="string" required>
  Your API key (`sk_live_...`)
</ParamField>

```bash theme={null}
curl -H "X-API-Key: sk_live_your_key_here" \
  https://api.prod.turen.io/api/v1/registered-agents
```

### Query Parameters

| Parameter | Type   | Default | Description                |
| --------- | ------ | ------- | -------------------------- |
| `limit`   | number | 50      | Number of agents to return |
| `offset`  | number | 0       | Pagination offset          |

### Response

```json theme={null}
{
  "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.

```bash theme={null}
curl -H "X-API-Key: sk_live_your_key_here" \
  https://api.prod.turen.io/api/v1/registered-agents/{id}
```

## Update Agent Status

Suspend or reactivate an agent.

```bash theme={null}
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.prod.turen.io/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 |

Returns `204 No Content` on success.

## Delete Agent

Remove an agent from your organization.

```bash theme={null}
curl -X DELETE \
  -H "X-API-Key: sk_live_your_key_here" \
  https://api.prod.turen.io/api/v1/registered-agents/{id}
```

### Query Parameters

| Parameter | Type    | Default | Description                         |
| --------- | ------- | ------- | ----------------------------------- |
| `hard`    | boolean | false   | Permanently delete (vs soft delete) |
| `reason`  | string  | -       | Reason for deletion                 |

<Warning>
  Hard deletion is permanent. The machine will need a new registration key to rejoin.
</Warning>