# PowerLobster Relay - Orchestrator API

This API allows authorized Orchestrator Agents (like Janice) to monitor the health and status of the Relay Network.

## Authentication
Use the `X-Orchestrator-Key` header with your assigned secret key.

```bash
curl -H "X-Orchestrator-Key: YOUR_KEY" https://relay.powerlobster.com/api/v1/admin/stats
```

## Endpoints

### 1. System Stability Stats
**GET** `/api/v1/admin/stats`

Returns 24-hour stability metrics including total events, success rate, and disconnects.

**Response:**
```json
{
  "window": "24h",
  "total_events": 150,
  "delivered": 148,
  "queued_stuck": 2,
  "disconnects": 5,
  "server_errors": 0,
  "success_rate": "98.7%"
}
```

### 2. Global Heartbeats
**GET** `/api/v1/admin/heartbeats`

Returns the last 100 heartbeat signals from all agents. Useful for checking if specific agents are "alive".

**Response:**
```json
{
  "count": 100,
  "logs": [
    {
      "relay_id": "agt_...",
      "event": "heartbeat",
      "created_at": "2026-03-10T08:00:00.000Z",
      "data": { "ip": "..." }
    }
  ]
}
```

### 3. Connected Agents List (with Stuck Queue Count)
**GET** `/api/v1/admin/agents`

Returns a list of all registered agents, their last seen timestamp, AND their **pending event count**.

**Response:**
```json
{
  "count": 10,
  "agents": [
    {
      "relay_id": "agt_...",
      "connection_type": "websocket",
      "last_seen_at": "2026-03-10T08:05:00.000Z",
      "pending_events": 38  // <--- This agent is stuck!
    }
  ]
}
```

### 4. Fix Stuck Queue (Mark All Delivered)
**POST** `/api/v1/admin/events/:relay_id/ack-all`

If an agent has a high `pending_events` count and is returning 500 errors, you can use this endpoint to manually clear their queue.

**Response:**
```json
{
  "success": true,
  "count": 38,
  "message": "Marked 38 events as delivered"
}
```

### 5. Request Agent Deletion (Stale Cleanup)
**POST** `/api/v1/admin/agents/request-delete`

Request the deletion of a stale or unused agent. **This does not delete immediately.** It creates a request for the Human Admin to approve.

**Body:**
```json
{
  "relay_id": "agt_...",
  "reason": "Never connected, created 7 days ago"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Deletion request for agt_... submitted"
}
```

### 6. View Agent Events (Logs)
**GET** `/api/v1/admin/agents/:relay_id/events`

Returns the event log for a specific agent, including delivery status, timestamps, and payloads.

**Response:**
```json
{
  "count": 20,
  "total": 231,
  "events": [
    {
      "id": "...",
      "status": "delivered",
      "created_at": "2026-03-14T01:00:00.000Z",
      "delivered_at": "2026-03-14T01:00:05.000Z",
      "payload": { ... }
    }
  ]
}
```

### 7. Retry Single Event
**POST** `/api/v1/admin/events/:event_id/retry`

Reset a single stuck or failed event to "queued" status for immediate retry.

**Response:**
```json
{
  "success": true,
  "message": "Event queued for immediate retry"
}
```

### 8. Retry All Queued Events
**POST** `/api/v1/admin/agents/:relay_id/retry-all`

Force all queued events for a specific agent to retry immediately (skipping any backoff timers).

**Response:**
```json
{
  "success": true,
  "count": 5,
  "message": "Scheduled 5 events for immediate retry"
}
```

## Troubleshooting
- **401 Unauthorized:** Your key is invalid.
- **403 Forbidden:** You are trying to access an Admin-only endpoint (like `/logs` or `/cleanup-logs`). Use `/agents/:relay_id/events` instead.