# 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
```