Add docs and project files - force for Culurien

docs/4_LOG/_originals_archive.backup/API.md

@@ -0,0 +1,154 @@
+# RedFlag API Reference
+
+## Base URL
+```
+http://your-server:8080/api/v1
+```
+
+## Authentication
+
+All admin endpoints require a JWT Bearer token:
+```bash
+Authorization: Bearer <your_jwt_token>
+```
+
+Agents use refresh tokens for long-lived authentication.
+
+---
+
+## Agent Endpoints
+
+### List All Agents
+```bash
+curl http://localhost:8080/api/v1/agents
+```
+
+### Get Agent Details
+```bash
+curl http://localhost:8080/api/v1/agents/{agent-id}
+```
+
+### Trigger Update Scan
+```bash
+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:
+```bash
+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
+```bash
+# 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
+```bash
+curl -X POST http://localhost:8080/api/v1/updates/{update-id}/approve
+```
+
+### Confirm Dependencies and Install
+```bash
+curl -X POST http://localhost:8080/api/v1/updates/{update-id}/confirm-dependencies
+```
+
+---
+
+## Registration Token Management
+
+### Generate Registration Token
+```bash
+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
+```bash
+curl -X GET https://redflag.wiuf.net/api/v1/admin/registration-tokens \
+  -H "Authorization: Bearer $ADMIN_TOKEN"
+```
+
+### Revoke Token
+```bash
+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
+```bash
+curl -X GET https://redflag.wiuf.net/api/v1/admin/rate-limits \
+  -H "Authorization: Bearer $ADMIN_TOKEN"
+```
+
+### Update Settings
+```bash
+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
+```json
+{
+  "status": "success",
+  "data": { ... }
+}
+```
+
+### Error Response
+```json
+{
+  "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
+```