> ## Documentation Index
> Fetch the complete documentation index at: https://docs.planasonix.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Pipeline agents
> Manage on-premises pipeline execution agents.
**Pipeline agents** run Planasonix workloads inside your network. These endpoints register agents, inspect health, revoke credentials, and fetch installers for Linux, Windows, and macOS.
Send `Authorization: Bearer ` on every request. See [Authentication](/api-reference/authentication).
## Base URL
```text theme={null}
https://api.planasonix.com
```
Agent routes use the `/api/agents` prefix (no `/v1` segment).
***
## List registered agents
```http theme={null}
GET /api/agents
```
**Query parameters (typical)**
| Parameter | Description |
| ----------------- | --------------------------------------- |
| `status` | `active`, `revoked`, `pending` |
| `label` | Substring match on human-readable label |
| `limit`, `cursor` | Pagination |
**Response `200 OK`**
```json theme={null}
{
"data": [
{
"id": "agt_01jq8prod01",
"label": "prod-etl-01.us-west.internal",
"platform": "linux",
"version": "2.14.3",
"status": "active",
"last_seen_at": "2025-03-27T14:59:30Z",
"created_at": "2025-02-10T11:20:00Z"
},
{
"id": "agt_01jq8stg01",
"label": "staging-windows-runner",
"platform": "windows",
"version": "2.14.2",
"status": "active",
"last_seen_at": "2025-03-27T14:58:02Z",
"created_at": "2025-02-15T09:05:00Z"
}
],
"meta": {
"page": { "limit": 50, "cursor": null }
}
}
```
***
## Register a new agent
```http theme={null}
POST /api/agents
```
**Request body**
```json theme={null}
{
"label": "analytics-k8s-pool-a",
"platform": "linux",
"tags": ["region:us-west-2", "env:production"],
"metadata": {
"k8s_namespace": "planasonix-agents",
"node_pool": "compute-optimized"
}
}
```
**Response `201 Created`**
```json theme={null}
{
"data": {
"id": "agt_01jq8new01",
"label": "analytics-k8s-pool-a",
"platform": "linux",
"status": "pending",
"enrollment_token": "plnx_enroll_01jq8xxxxxxxxxxxxxxxx_only_shown_once",
"token_expires_at": "2025-03-27T20:00:00Z",
"created_at": "2025-03-27T15:00:00Z"
}
}
```
The enrollment token is shown only at creation time. Store it in a secret manager before closing the response.
***
## Get agent details
```http theme={null}
GET /api/agents/{id}
```
**Response `200 OK`**
```json theme={null}
{
"data": {
"id": "agt_01jq8prod01",
"label": "prod-etl-01.us-west.internal",
"platform": "linux",
"version": "2.14.3",
"status": "active",
"tags": ["region:us-west-2", "env:production"],
"capabilities": ["spark", "python_3_11"],
"last_seen_at": "2025-03-27T14:59:30Z",
"created_at": "2025-02-10T11:20:00Z",
"metadata": {
"hostname": "etl-prod-01.internal.example.com"
}
}
}
```
***
## Deregister an agent
```http theme={null}
DELETE /api/agents/{id}
```
Removes the agent record and invalidates its credentials. In-flight work may fail; drain the agent first in production.
**Response `204 No Content`**
***
## Get agent health status
```http theme={null}
GET /api/agents/{id}/health
```
**Response `200 OK`**
```json theme={null}
{
"data": {
"agent_id": "agt_01jq8prod01",
"status": "healthy",
"heartbeat_at": "2025-03-27T14:59:30Z",
"cpu_percent": 34.2,
"memory_percent": 61.0,
"disk_free_gb": 412.5,
"active_jobs": 2,
"queue_depth": 0,
"last_error": null
}
}
```
***
## List currently connected agents
```http theme={null}
GET /api/agents/connected
```
Returns agents with a recent control-plane heartbeat (typically last 2 minutes).
**Response `200 OK`**
```json theme={null}
{
"data": [
{
"id": "agt_01jq8prod01",
"label": "prod-etl-01.us-west.internal",
"connected_since": "2025-03-27T14:45:00Z",
"remote_ip": "203.0.113.45"
}
]
}
```
***
## Revoke agent access
```http theme={null}
POST /api/agents/revoke/{id}
```
Immediately blocks new work and invalidates session credentials. The agent record remains for audit.
**Request body (optional)**
```json theme={null}
{
"reason": "compromised_token_suspected"
}
```
**Response `200 OK`**
```json theme={null}
{
"data": {
"id": "agt_01jq8prod01",
"status": "revoked",
"revoked_at": "2025-03-27T15:02:00Z"
}
}
```
***
## Re-enable revoked agent
```http theme={null}
POST /api/agents/enable/{id}
```
Requires a fresh enrollment or token rotation flow depending on your workspace policy.
**Response `200 OK`**
```json theme={null}
{
"data": {
"id": "agt_01jq8prod01",
"status": "pending",
"enrollment_token": "plnx_enroll_01jq8yyyyyyyyyyyy_only_shown_once",
"token_expires_at": "2025-03-27T21:00:00Z"
}
}
```
***
## Download agent installer
```http theme={null}
GET /api/agents/installer/{agentId}/{platform}
```
One of `linux`, `windows`, `macos`. Response is a binary archive or installer package with appropriate `Content-Type` and `Content-Disposition`.
**Response `200 OK`**
Binary body (for example `application/gzip` for Linux bundles). No JSON envelope.
***
## Get manual installation instructions
```http theme={null}
GET /api/agents/manual-install/{agentId}
```
**Response `200 OK`**
```json theme={null}
{
"data": {
"agent_id": "agt_01jq8new01",
"steps": [
{
"order": 1,
"title": "Download bundle",
"command": "curl -fsSL \"https://api.planasonix.com/api/agents/installer/agt_01jq8new01/linux\" -o planasonix-agent.tar.gz"
},
{
"order": 2,
"title": "Extract and install",
"command": "sudo ./install.sh --token \"$PLANASONIX_ENROLLMENT_TOKEN\""
}
],
"environment_variables": {
"PLANASONIX_API_HOST": "https://api.planasonix.com",
"PLANASONIX_AGENT_ID": "agt_01jq8new01"
}
}
}
```
***
## Related topics
Architecture and operations in the product docs.
Common connectivity and credential issues.