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 agent token. Registration authenticates with the API key, sent either as the X-API-Key header or as an apiKey field in the JSON body (both are accepted; the header takes priority if both are present).

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",
    "type": "docker"
  }'

type is the agent's mode, "docker" or "kubernetes".

Response:

{
  "agentId": "agent_7f3c9b2a",
  "token": "a1b2c3d4e5f6..."
}

The token is used for subsequent push requests and it doesn't expire. The agent stores it locally and reuses it across restarts instead of registering again every time. How often it pushes is controlled by the agent's own KUBEWATCH_INTERVAL setting (default 15s), not by the server.

Push metrics

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

Called on the agent's own interval (default every 15 seconds, via KUBEWATCH_INTERVAL) to deliver the current snapshot. See the Metrics API for the real container/pod/node field shapes, including the CPU, memory, and network fields the agent reads from the Docker stats API and includes on every pushed container (zero if that container's stats call failed this cycle, not omitted).

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 '{
    "containers": [
      {
        "id": "a1b2c3d4e5f6",
        "shortId": "a1b2c3d4e5f6",
        "name": "nginx-prod",
        "image": "nginx:1.25",
        "status": "running",
        "state": "running",
        "source": "docker",
        "ports": []
      }
    ],
    "nodes": [],
    "pods": [],
    "version": "1.4.2"
  }'

Response:

{ "ok": true, "logRequests": [] }

logRequests carries any pending log-stream requests the dashboard queued for this agent since its last push.

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",
    "type": "docker",
    "status": "online",
    "version": "1.4.2",
    "containerCount": 8,
    "podCount": 0,
    "nodeCount": 0,
    "lastSeen": "2026-06-16T10:00:05Z",
    "createdAt": "2026-06-01T10:00:00Z"
  }
]

status is online if the agent pushed within the last 90 seconds, offline otherwise.

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