# Red Alert — Agent Connection Guide
# https://redalert.cc/agents.txt
#
# Red Alert is a break-glass communication app. Agents (machines) can
# send alerts that escalate through push → SMS → phone call until the
# human acknowledges. This file explains how to connect your agent.

## Quick Start

To connect to a human's Red Alert, you need their email address.
You do NOT need an account — the human approves you via a link.

## Step 1: Request a Connection

POST /api/v1/connect/request
Content-Type: application/json

{
  "email": "human@example.com",
  "name": "Your Agent Name",
  "description": "Brief description of what you monitor"
}

Response (201):
{
  "data": {
    "connectionId": "clx...",
    "approveUrl": "https://redalert.cc/connect/approve/<token>",
    "expiresAt": "2026-03-17T18:00:00.000Z"
  }
}

Send the approveUrl to the human. They click it, log in, and approve.
The link expires in 24 hours.

## Step 2: Poll for Approval

GET /api/v1/connect/status/<connectionId>

Response when pending:
{ "data": { "status": "pending" } }

Response when approved (API key included ONE TIME):
{ "data": { "status": "approved", "apiKey": "ra_ak_..." } }

Response when denied:
{ "data": { "status": "denied" } }

Poll every 30–60 seconds. The API key is returned exactly once on the
first poll after approval. Store it securely — it cannot be retrieved again.

## Step 3: Send Alerts

POST /api/v1/alerts
Authorization: Bearer ra_ak_...
Content-Type: application/json

{
  "title": "Production database CPU at 95%",
  "body": "db-prod-01 has been above threshold for 5 minutes",
  "priority": "critical",
  "actions": [
    { "id": "restart", "label": "Restart DB" },
    { "id": "silence", "label": "Silence 1hr" }
  ],
  "callbackUrl": "https://your-agent.com/webhook",
  "dedupeKey": "db-cpu-prod-01"
}

Priority levels: critical, high, normal, low
Each level has different escalation timing (SMS delay, call delay).

## Step 4: Poll Alert Status

GET /api/v1/alerts/<alertId>/status
Authorization: Bearer ra_ak_...

Returns the alert status, including whether the human acknowledged,
resolved, snoozed, or took a custom action.

## Rate Limits

- Connection requests: 5 per email per hour
- Alerts: Configurable per connection (default 100/day)

## Alert Priority Escalation

  critical: SMS after 1 min, call after 3 min
  high:     SMS after 3 min, call after 10 min
  normal:   SMS after 5 min, call after 15 min
  low:      SMS after 10 min, no call

## API Key Format

All API keys start with "ra_ak_" followed by 40 hex characters.
Use as a Bearer token in the Authorization header.

## Base URL

Production: https://redalert.cc
Local dev:  http://localhost:3080