Pipeline 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 <api_key> on every request. See Authentication.

Base URL

https://api.planasonix.com

Agent routes use the /api/agents prefix (no /v1 segment).

List registered agents

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

{
  "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

POST /api/agents

Request body

{
  "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

{
  "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

GET /api/agents/{id}

Response 200 OK

{
  "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

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

GET /api/agents/{id}/health

Response 200 OK

{
  "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

GET /api/agents/connected

Returns agents with a recent control-plane heartbeat (typically last 2 minutes). Response 200 OK

{
  "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

POST /api/agents/revoke/{id}

Immediately blocks new work and invalidates session credentials. The agent record remains for audit. Request body (optional)

{
  "reason": "compromised_token_suspected"
}

Response 200 OK

{
  "data": {
    "id": "agt_01jq8prod01",
    "status": "revoked",
    "revoked_at": "2025-03-27T15:02:00Z"
  }
}

Re-enable revoked agent

POST /api/agents/enable/{id}

Requires a fresh enrollment or token rotation flow depending on your workspace policy. Response 200 OK

{
  "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

GET /api/agents/installer/{agentId}/{platform}

string

required

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

GET /api/agents/manual-install/{agentId}

Response 200 OK

{
  "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"
    }
  }
}

Architecture and operations in the product docs.

Troubleshooting agents

Common connectivity and credential issues.

Overview

Data platform

Orchestration

Integration

Governance

Iceberg Catalog

Platform

Pipeline agents

Base URL

List registered agents

Register a new agent

Get agent details

Deregister an agent

Get agent health status

List currently connected agents

Revoke agent access

Re-enable revoked agent

Download agent installer

Get manual installation instructions

Pipeline agents

Troubleshooting agents

​Base URL

​List registered agents

​Register a new agent

​Get agent details

​Deregister an agent

​Get agent health status

​List currently connected agents

​Revoke agent access

​Re-enable revoked agent

​Download agent installer

​Get manual installation instructions

​Related topics

Pipeline agents

Troubleshooting agents

Base URL

List registered agents

Register a new agent

Get agent details

Deregister an agent

Get agent health status

List currently connected agents

Revoke agent access

Re-enable revoked agent

Download agent installer

Get manual installation instructions

Related topics