Redflag/docs/4_LOG/October_2025/Development-Documentation/API.md

RedFlag API Reference

Base URL

http://your-server:8080/api/v1

Authentication

All admin endpoints require a JWT Bearer token:

Authorization: Bearer <your_jwt_token>

Agents use refresh tokens for long-lived authentication.

---

Agent Endpoints

List All Agents

curl http://localhost:8080/api/v1/agents

Get Agent Details

curl http://localhost:8080/api/v1/agents/{agent-id}

Trigger Update Scan

curl -X POST http://localhost:8080/api/v1/agents/{agent-id}/scan

Token Renewal

Agents use this to exchange refresh tokens for new access tokens:

curl -X POST http://localhost:8080/api/v1/agents/renew \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "uuid",
    "refresh_token": "long-lived-token"
  }'

---

Update Endpoints

List All Updates

# All updates
curl http://localhost:8080/api/v1/updates

# Filter by severity
curl http://localhost:8080/api/v1/updates?severity=critical

# Filter by status
curl http://localhost:8080/api/v1/updates?status=pending

Approve an Update

curl -X POST http://localhost:8080/api/v1/updates/{update-id}/approve

Confirm Dependencies and Install

curl -X POST http://localhost:8080/api/v1/updates/{update-id}/confirm-dependencies

---

Registration Token Management

Generate Registration Token

curl -X POST https://redflag.wiuf.net/api/v1/admin/registration-tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{
    "label": "Production Servers",
    "expires_in": "24h",
    "max_seats": 5
  }'

List Tokens

curl -X GET https://redflag.wiuf.net/api/v1/admin/registration-tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Revoke Token

curl -X DELETE https://redflag.wiuf.net/api/v1/admin/registration-tokens/rf-tok-abc123 \
  -H "Authorization: Bearer $ADMIN_TOKEN"

---

Rate Limit Management

View Current Settings

curl -X GET https://redflag.wiuf.net/api/v1/admin/rate-limits \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Update Settings

curl -X PUT https://redflag.wiuf.net/api/v1/admin/rate-limits \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{
    "agent_registration": {"requests": 10, "window": "1m", "enabled": true},
    "admin_operations": {"requests": 200, "window": "1m", "enabled": true}
  }'

---

Response Formats

Success Response

{
  "status": "success",
  "data": { ... }
}

Error Response

{
  "error": "error message",
  "code": "ERROR_CODE"
}

---

Rate Limiting

API endpoints are rate-limited by category:

• Agent Registration: 10 requests/minute (configurable)
• Agent Check-ins: 60 requests/minute (configurable)
• Admin Operations: 200 requests/minute (configurable)

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1234567890