-
Notifications
You must be signed in to change notification settings - Fork 1
API Reference
The White-Ops API is a RESTful HTTP API served by the FastAPI backend at http://localhost:8000. All endpoints are prefixed with /api/v1/ unless otherwise noted.
All endpoints except /api/v1/auth/login and /health require a valid JWT token.
Include the token in the Authorization header:
Authorization: Bearer <your-jwt-token>
Tokens are obtained via the login endpoint and expire after the configured JWT_ACCESS_TOKEN_EXPIRE_MINUTES (default: 1440 minutes / 24 hours).
Pagination:
GET /api/v1/tasks?page=1&per_page=20
Response includes:
{
"items": [...],
"total": 150,
"page": 1,
"per_page": 20,
"pages": 8
}Error Responses:
{
"detail": "Human-readable error message",
"request_id": "abc12345"
}| Status | Meaning |
|---|---|
| 400 | Bad request / validation error |
| 401 | Unauthorized (missing or invalid token) |
| 403 | Forbidden (insufficient permissions) |
| 404 | Resource not found |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
Source: server/app/api/v1/auth.py
Authenticate and receive a JWT token.
Auth required: No
Request:
{
"email": "admin@whiteops.local",
"password": "your-password"
}Response (200):
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer",
"user": {
"id": "uuid",
"email": "admin@whiteops.local",
"role": "admin"
}
}Get the current authenticated user.
Auth required: Yes
Response (200):
{
"id": "uuid",
"email": "admin@whiteops.local",
"role": "admin",
"created_at": "2025-01-01T00:00:00Z"
}Change the current user's password.
Auth required: Yes
Request:
{
"current_password": "old-password",
"new_password": "new-password"
}Response (200):
{
"message": "Password updated successfully"
}Source: server/app/api/v1/agents.py
List all agents.
Auth required: Yes | Permission: agents:read
Query params: status, page, per_page
Response (200):
{
"items": [
{
"id": "uuid",
"name": "Research Assistant",
"description": "Searches the web and summarizes",
"status": "active",
"llm_provider": "anthropic",
"llm_model": "claude-sonnet-4-20250514",
"tools": ["web_search", "summarizer", "notes"],
"tasks_completed": 42,
"created_at": "2025-01-01T00:00:00Z"
}
],
"total": 5,
"page": 1,
"per_page": 20
}Create a new agent.
Auth required: Yes | Permission: agents:create
Request:
{
"name": "Research Assistant",
"description": "Searches the web and summarizes findings",
"llm_provider": "anthropic",
"llm_model": "claude-sonnet-4-20250514",
"tools": ["web_search", "summarizer", "notes"],
"system_prompt": "You are a research assistant..."
}Response (201):
{
"id": "uuid",
"name": "Research Assistant",
"status": "idle",
"created_at": "2025-01-01T00:00:00Z"
}Get agent details.
Auth required: Yes | Permission: agents:read
Update an agent.
Auth required: Yes | Permission: agents:update
Request: Partial update -- include only fields to change.
Delete an agent (soft delete).
Auth required: Yes | Permission: agents:delete
Start an agent so it can receive tasks.
Auth required: Yes | Permission: agents:update
Stop an agent gracefully.
Auth required: Yes | Permission: agents:update
Source: server/app/api/v1/tasks.py
List tasks with optional filters.
Auth required: Yes | Permission: tasks:read
Query params: status, priority, agent_id, date_from, date_to, search, page, per_page
Response (200):
{
"items": [
{
"id": "uuid",
"title": "Research AI Trends",
"description": "Search for top AI trends...",
"status": "completed",
"priority": "medium",
"agent_id": "uuid",
"agent_name": "Research Assistant",
"result": "Here are the top 5 AI trends...",
"error": null,
"created_at": "2025-01-01T00:00:00Z",
"started_at": "2025-01-01T00:00:05Z",
"completed_at": "2025-01-01T00:01:30Z"
}
],
"total": 100
}Create a new task.
Auth required: Yes | Permission: tasks:create
Request:
{
"title": "Research AI Trends",
"description": "Search for the top 5 AI trends in 2025...",
"agent_id": "uuid",
"priority": "medium",
"required_tools": ["web_search", "summarizer"],
"scheduled_at": null,
"attachments": []
}Response (201):
{
"id": "uuid",
"title": "Research AI Trends",
"status": "pending",
"created_at": "2025-01-01T00:00:00Z"
}Get full task details including execution log and results.
Auth required: Yes | Permission: tasks:read
Update a task (status, result, error).
Auth required: Yes | Permission: tasks:update
Delete a task.
Auth required: Yes | Permission: tasks:delete
Cancel a pending or in-progress task.
Auth required: Yes | Permission: tasks:update
Source: server/app/api/v1/workflows.py
List all workflows.
Auth required: Yes | Permission: workflows:read
Create a workflow.
Auth required: Yes | Permission: workflows:create
Request:
{
"name": "Weekly Report Pipeline",
"description": "Collects data, analyzes, and generates report",
"steps": [
{
"id": "step_1",
"type": "task",
"agent_id": "uuid",
"task_config": { "title": "Collect data", "description": "..." },
"depends_on": []
},
{
"id": "step_2",
"type": "task",
"agent_id": "uuid",
"task_config": { "title": "Analyze data", "description": "..." },
"depends_on": ["step_1"]
},
{
"id": "step_3",
"type": "notify",
"config": { "channel": "email", "to": "team@example.com" },
"depends_on": ["step_2"]
}
]
}Get workflow details.
Auth required: Yes | Permission: workflows:read
Update a workflow.
Auth required: Yes | Permission: workflows:update
Delete a workflow.
Auth required: Yes | Permission: workflows:delete
Execute a workflow.
Auth required: Yes | Permission: workflows:create
Response (202):
{
"run_id": "uuid",
"workflow_id": "uuid",
"status": "running",
"started_at": "2025-01-01T00:00:00Z"
}Source: server/app/api/v1/messages.py
List messages.
Auth required: Yes | Permission: messages:read
Query params: agent_id, thread_id, page, per_page
Send a message (agent-to-agent or system notification).
Auth required: Yes | Permission: messages:read
Request:
{
"from_agent_id": "uuid",
"to_agent_id": "uuid",
"subject": "Task handoff",
"body": "Here are the research results...",
"thread_id": "uuid-or-null"
}Get a specific message.
Auth required: Yes | Permission: messages:read
Source: server/app/api/v1/files.py
List files.
Auth required: Yes | Permission: files:read
Query params: agent_id, mime_type, page, per_page
Upload a file. Multipart form data.
Auth required: Yes | Permission: files:upload
Request: multipart/form-data with file field.
Response (201):
{
"id": "uuid",
"filename": "report.pdf",
"size": 245678,
"mime_type": "application/pdf",
"uploaded_by": "admin",
"created_at": "2025-01-01T00:00:00Z"
}Download a file.
Auth required: Yes | Permission: files:read
Response: Binary file content with appropriate Content-Type header.
Delete a file.
Auth required: Yes | Permission: files:delete
Source: server/app/api/v1/workers.py
List all workers.
Auth required: Yes | Permission: workers:read
Response (200):
{
"items": [
{
"id": "uuid",
"name": "worker-01",
"hostname": "server-01",
"ip_address": "192.168.1.100",
"status": "online",
"max_agents": 5,
"active_agents": 2,
"cpu_cores": 8,
"memory_total_mb": 16384,
"cpu_usage_percent": 45.2,
"memory_usage_percent": 62.1,
"disk_usage_percent": 38.5,
"last_heartbeat": "2025-01-01T00:00:30Z",
"approved": true
}
]
}Register a new worker (called by workers, not users).
Auth required: No (internal endpoint)
Request:
{
"name": "worker-01",
"hostname": "server-01",
"ip_address": "192.168.1.100",
"max_agents": 5,
"cpu_cores": 8,
"memory_total_mb": 16384,
"os_info": {
"os": "Linux",
"os_version": "6.1.0",
"architecture": "x86_64",
"python_version": "3.12.0"
}
}Send a heartbeat with system metrics (called by workers).
Auth required: No (internal endpoint)
Request:
{
"cpu_usage_percent": 45.2,
"memory_usage_percent": 62.1,
"disk_usage_percent": 38.5
}Get tasks assigned to a worker (called by workers).
Auth required: No (internal endpoint)
Approve a pending worker.
Auth required: Yes | Permission: workers:approve
Remove a worker from the fleet.
Auth required: Yes | Permission: workers:remove
Source: server/app/api/v1/admin.py
List all users.
Auth required: Yes | Permission: users:read
Create a new user.
Auth required: Yes | Permission: users:create
Request:
{
"email": "operator@whiteops.local",
"password": "secure-password",
"name": "Operator User",
"role": "operator"
}Update a user.
Auth required: Yes | Permission: users:update
Delete a user.
Auth required: Yes | Permission: users:delete
Get the audit log.
Auth required: Yes | Permission: audit:read
Query params: action, user_id, resource_type, date_from, date_to, page, per_page
Source: server/app/api/v1/dashboard.py
Get dashboard KPI data.
Auth required: Yes
Response (200):
{
"agents": { "total": 10, "active": 5, "idle": 3, "stopped": 2 },
"tasks": { "total": 500, "pending": 10, "in_progress": 5, "completed": 470, "failed": 15 },
"workers": { "total": 3, "online": 3, "offline": 0 },
"success_rate": 96.9
}Get chart data for the dashboard.
Auth required: Yes
Query params: period (7d, 30d, 90d)
Response (200):
{
"tasks_over_time": [
{ "date": "2025-01-01", "completed": 15, "failed": 1 }
],
"agent_utilization": [
{ "agent": "Research Assistant", "tasks": 42 }
],
"status_distribution": {
"completed": 470,
"failed": 15,
"pending": 10,
"in_progress": 5
}
}Get system health status.
Auth required: Yes
Response (200):
{
"api": "healthy",
"database": "healthy",
"redis": "healthy",
"minio": "healthy",
"workers": [
{ "name": "worker-01", "status": "online", "cpu": 45.2, "memory": 62.1 }
]
}Source: server/app/api/v1/settings.py
Get all settings grouped by category.
Auth required: Yes | Permission: settings:read
Response (200):
{
"llm": {
"default_provider": "anthropic",
"default_model": "claude-sonnet-4-20250514"
},
"email": {
"mail_domain": "whiteops.local",
"smtp_host": ""
},
"security": {
"jwt_expire_minutes": 1440,
"rate_limit": 120
},
"general": {
"app_name": "White-Ops",
"debug": false
},
"notifications": {
"task_completion": true,
"worker_alerts": true
},
"storage": {
"minio_endpoint": "minio:9000",
"minio_bucket": "whiteops-files"
}
}Update settings (partial update).
Auth required: Yes | Permission: settings:update
Request:
{
"llm": {
"default_provider": "openai",
"default_model": "gpt-4o"
}
}Source: server/app/api/v1/analytics.py
Get task analytics.
Auth required: Yes
Query params: period (24h, 7d, 30d, 90d, custom range)
Response (200):
{
"total": 500,
"completed": 470,
"failed": 15,
"success_rate": 96.9,
"avg_duration_seconds": 85.3,
"by_priority": {
"low": { "total": 100, "completed": 98 },
"medium": { "total": 250, "completed": 240 },
"high": { "total": 150, "completed": 132 }
},
"trend": [
{ "date": "2025-01-01", "completed": 15, "failed": 1 }
]
}Get agent performance analytics.
Auth required: Yes
Response (200):
{
"agents": [
{
"id": "uuid",
"name": "Research Assistant",
"tasks_completed": 42,
"tasks_failed": 2,
"avg_duration_seconds": 72.5,
"success_rate": 95.5,
"tool_usage": {
"web_search": 38,
"summarizer": 35,
"notes": 20
}
}
]
}Get worker utilization analytics.
Auth required: Yes
Source: server/app/api/v1/knowledge.py
List knowledge base entries.
Auth required: Yes
Query params: category, tags, search, page, per_page
Create a knowledge base entry.
Auth required: Yes
Request:
{
"title": "Company PTO Policy",
"content": "All employees receive 20 days PTO...",
"category": "HR Policies",
"tags": ["hr", "pto", "leave"]
}Get a knowledge base entry.
Auth required: Yes
Update an entry.
Auth required: Yes
Delete an entry.
Auth required: Yes
Full-text search across the knowledge base.
Auth required: Yes
Query params: q (search query), category, tags
Source: server/app/api/v1/collaboration.py
List collaboration sessions.
Auth required: Yes
Create a collaboration session.
Auth required: Yes
Request:
{
"title": "Q4 Report Preparation",
"description": "Multiple agents collaborate on the quarterly report",
"agent_ids": ["uuid-1", "uuid-2", "uuid-3"],
"goal": "Produce a comprehensive Q4 report"
}Get session details, messages, and outputs.
Auth required: Yes
Send a message within a collaboration session.
Auth required: Yes
Source: server/app/api/v1/schedules.py
List all scheduled tasks.
Auth required: Yes
Create a scheduled task.
Auth required: Yes
Request:
{
"name": "Daily Report",
"description": "Generate daily summary report",
"cron_expression": "0 9 * * 1-5",
"task_config": {
"title": "Generate Daily Report",
"description": "...",
"agent_id": "uuid",
"priority": "medium"
},
"enabled": true
}Update a schedule.
Auth required: Yes
Delete a schedule.
Auth required: Yes
Trigger a scheduled task immediately.
Auth required: Yes
Source: server/app/api/v1/exports.py
Export tasks as CSV or JSON.
Auth required: Yes
Query params: format (csv, json), status, date_from, date_to
Export agent data.
Auth required: Yes
Query params: format (csv, json)
Export audit log.
Auth required: Yes | Permission: audit:read
Query params: format (csv, json), date_from, date_to
Source: server/app/api/websocket.py
Connect to the real-time event stream.
Connection:
const ws = new WebSocket("ws://localhost:8000/ws");
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log(data.type, data.data);
};Event Types:
| Event | Payload | Description |
|---|---|---|
agent.status |
{ agent_id, status } |
Agent state changed |
task.created |
{ task_id, title, agent_id } |
New task created |
task.updated |
{ task_id, status } |
Task status updated |
task.completed |
{ task_id, result } |
Task finished successfully |
task.failed |
{ task_id, error } |
Task execution failed |
worker.online |
{ worker_id, name } |
Worker connected |
worker.offline |
{ worker_id, name } |
Worker disconnected |
message.new |
{ message_id, from, to, subject } |
New message sent |
notification |
{ title, message, priority } |
System notification |
system.alert |
{ type, message, severity } |
System alert |
Subscribe to Specific Events:
ws.send(JSON.stringify({
action: "subscribe",
event_types: ["task.completed", "task.failed"]
}));Broadcast: The server broadcasts events to all connected clients. Subscriptions allow clients to filter by event type.