API.md

AgentWatch REST & WebSocket API Specification

AgentWatch provides clean, OpenAPI-compliant REST endpoints and WebSocket channels for telemetry collection and real-time monitoring.

---

📡 REST API Reference

Base URL: http://localhost:8000 (Default)

🤖 Agents

POST /agents/register

Register a new agent instance or update an existing registration.

Request Body:

{
  "agent_id": "coding-agent-1",
  "name": "Coding Agent",
  "model": "gpt-4o",
  "system_info": {
    "cpu_percent": 15.2,
    "memory_mb": 340.5
  }
}

POST /agents/heartbeat (Alias: POST /heartbeat)

Send a periodic liveness heartbeat from an agent.

Request Body:

{
  "agent_id": "coding-agent-1",
  "system_info": {
    "cpu_percent": 12.0,
    "memory_mb": 310.0
  }
}

GET /agents

List registered agents with optional status filtering.

Query Parameters:

• status (optional): Filter by active, idle, or offline.

---

📋 Tasks

POST /tasks/start

Record the start of a named task execution.

Request Body:

{
  "task_id": "task-8f92a1",
  "agent_id": "coding-agent-1",
  "name": "Fix authentication bug"
}

POST /tasks/end

Record task completion or failure.

Request Body:

{
  "task_id": "task-8f92a1",
  "agent_id": "coding-agent-1",
  "status": "SUCCESS",
  "result": "Resolved token verification logic."
}

GET /tasks

Retrieve historical task execution records.

Query Parameters:

• agent_id (optional): Filter by agent ID.
• status (optional): Filter by RUNNING, SUCCESS, or FAILED.
• limit (optional, default: 50): Number of records to return.

---

📊 Telemetry & Resource Metrics

POST /metrics

Log process resource utilization and LLM token counts.

Request Body:

{
  "agent_id": "coding-agent-1",
  "task_id": "task-8f92a1",
  "cpu_percent": 35.2,
  "memory_mb": 420.0,
  "tokens": 1520,
  "prompt_tokens": 1000,
  "completion_tokens": 520,
  "model": "gpt-4o"
}

GET /metrics

Fetch recorded metric data points.

---

📜 Logs & Error Events

POST /logs

Post a log entry from an agent.

GET /logs

Query historical log streams.

POST /errors

Record an exception event, retry attempt, or stack trace.

GET /errors

Retrieve logged error events.

---

💸 Analytics & Pricing

GET /analytics/summary

Get high-level summary metrics across agents, tasks, token consumption, and cost.

GET /analytics/cost

Aggregated daily, weekly, and monthly cost reports broken down by agent and model.

GET /analytics/pricing

View active token pricing per 1,000 tokens for supported models.

POST /analytics/pricing

Register or update custom model pricing.

---

⚡ WebSocket API Reference

• Endpoint: ws://localhost:8000/ws/telemetry
• Format: JSON Payload

Subscribed Event Types:

• agent_register
• heartbeat
• task_start
• task_end
• metric
• log
• error
• alert