Agents API

The Agents API is used by the kubewatch-agent binary to register itself and push metrics. You can also use it to list or delete agents programmatically.

Register an agent

POST /api/v1/agents/register

Called by the agent on startup to obtain an agent ID and short-lived agent token.

Request:

curl -X POST https://YOUR_KUBEWATCH_URL/api/v1/agents/register \
  -H "X-API-Key: kw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-web",
    "version": "1.4.2",
    "platform": "docker",
    "hostname": "prod-web-01"
  }'

Response:

{
  "agentId": "agent_7f3c9b2a",
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "tokenExpiresIn": 3600,
  "pushIntervalSeconds": 15
}

The token is used for subsequent push requests. When it expires, the agent re-registers automatically.

Push metrics

POST /api/v1/agents/{agentId}/push

Called every pushIntervalSeconds to deliver current metrics.

Request:

curl -X POST https://YOUR_KUBEWATCH_URL/api/v1/agents/agent_7f3c9b2a/push \
  -H "Authorization: Bearer <agent-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2026-06-16T10:00:00Z",
    "containers": [
      {
        "id": "a1b2c3d4e5f6",
        "name": "nginx-prod",
        "image": "nginx:1.25",
        "status": "running",
        "cpuPercent": 12.4,
        "memoryMB": 48,
        "memoryLimitMB": 512,
        "networkRxBytes": 10240,
        "networkTxBytes": 8192,
        "restartCount": 0
      }
    ],
    "nodes": [],
    "pods": []
  }'

Response:

{ "ok": true }

List agents

GET /api/v1/agents

Returns all agents registered for your organization.

Request:

curl -H "Authorization: Bearer <your-jwt>" \
  https://YOUR_KUBEWATCH_URL/api/v1/agents

Response:

[
  {
    "id": "agent_7f3c9b2a",
    "name": "prod-web",
    "platform": "docker",
    "hostname": "prod-web-01",
    "version": "1.4.2",
    "lastSeen": "2026-06-16T10:00:05Z",
    "status": "connected",
    "containerCount": 8
  }
]

Delete an agent

DELETE /api/v1/agents/{agentId}

Removes an agent and all its stored metrics. This action is irreversible.

curl -X DELETE \
  -H "Authorization: Bearer <your-jwt>" \
  https://YOUR_KUBEWATCH_URL/api/v1/agents/agent_7f3c9b2a

Response: 204 No Content