Docs

REST API Reference

Base URL: http://localhost:8000

Full interactive documentation is auto-generated by FastAPI at:

http://localhost:8000/docs

Dashboard

`GET /`

Returns the Foreman HTML dashboard page.

Stats

`GET /api/stats`

Returns aggregate system metrics.

Response:

{
  "total_workers": 3,
  "online_workers": 2,
  "total_jobs": 127,
  "completed_jobs": 120,
  "failed_jobs": 5,
  "running_jobs": 2,
  "total_tasks_completed": 8412,
  "uptime_seconds": 3641
}

Jobs

`GET /api/jobs`

Returns all jobs with status, task counts, and timestamps.

Response (array):

[
  {
    "id": "job_abc123",
    "status": "completed",
    "task_count": 5,
    "created_at": "2024-01-15T10:00:00Z",
    "completed_at": "2024-01-15T10:00:12Z",
    "client_id": "client_xyz"
  }
]

`GET /api/jobs/{job_id}`

Returns full job detail.

Path params: job_id string

Response:

{
  "id": "job_abc123",
  "status": "completed",
  "tasks": [
    {
      "id": "task_001",
      "index": 0,
      "status": "completed",
      "worker_id": "worker_001",
      "attempt": 1,
      "result_available": true
    }
  ]
}

Workers

`GET /api/workers`

Returns all registered workers.

Response (array):

[
  {
    "id": "worker_001",
    "type": "pc",
    "platform": "linux",
    "status": "online",
    "active_tasks": 1,
    "total_completed": 412,
    "last_heartbeat": "2024-01-15T10:05:00Z"
  },
  {
    "id": "worker_002",
    "type": "android_kotlin",
    "platform": "android",
    "status": "busy",
    "active_tasks": 1,
    "total_completed": 38,
    "last_heartbeat": "2024-01-15T10:05:01Z"
  }
]

`DELETE /api/workers/{worker_id}`

Deregisters and removes a specific worker.

Path params: worker_id string

`GET /api/workers/{worker_id}/failures`

Returns the failure history for a specific worker.

Response (array):

[
  {
    "task_id": "task_099",
    "job_id": "job_xyz",
    "error_type": "ValueError",
    "error_message": "bad input",
    "failed_at": "2024-01-15T09:55:00Z"
  }
]

Scheduler

`GET /api/scheduler/algorithms`

Returns a list of all available scheduler algorithm IDs.

`GET /api/scheduler/config`

Returns the current active scheduler configuration.

`POST /api/scheduler/activate/{algorithm}`

Switches the active scheduler.

Path params: algorithm — one of fifo, round_robin, least_loaded, performance, priority, aras, edas, mabac, wrr

`PUT /api/scheduler/config`

Updates scheduler configuration (e.g., MCDM weights).

Request body:

{
  "algorithm": "aras",
  "weights": {
    "cpu": 0.3,
    "memory": 0.2,
    "throughput": 0.3,
    "failure_rate": 0.1,
    "latency": 0.1
  }
}

`GET /api/scheduling-info`

Returns scheduler state + per-worker criteria scores + queue depth.

Checkpoints

`GET /api/checkpoints/job/{job_id}`

Returns all checkpoint records for a job.

`GET /api/checkpoints/recovery-events`

Returns all task recovery events across all jobs.

Evaluation

`GET /api/evaluation/metrics`

Summary evaluation metrics across all workers and jobs.

`GET /api/evaluation/load-distribution`

Task distribution breakdown per worker.

`GET /api/evaluation/throughput-history`

Time-series throughput data (tasks/second over time).

`GET /api/evaluation/worker-performance`

Per-worker performance metrics: avg task time, throughput, energy, failure rate.

Database

`DELETE /api/database/clear`

!!! caution “Destructive” Clears all job, task, worker, and checkpoint records from the database.

Error Responses

All endpoints return standard HTTP error codes:

Code	Meaning
`404`	Resource not found
`422`	Validation error (invalid request body)
`500`	Internal server error

Error body:

{
  "detail": "Error description here"
}