API Reference

Homeio exposes a REST API at http://your-server-ip:3000. All endpoints require the Authorization: Bearer <token> header after login.

Note: The API is currently unstable and may change between versions. Pin to a specific tag when scripting against it.

POST

Authentication

POST/api/auth/login

Authenticate with username and password to receive a session token.

Request body

{
  "username": "admin",
  "password": "your-password"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": { "id": 1, "username": "admin" }
}

GET

Apps

GET/api/apps

List all installed Docker Compose applications and their status.

Response

[
  {
    "id": "jellyfin",
    "name": "Jellyfin",
    "status": "running",
    "cpu": 2.1,
    "memory": 512
  }
]

GET

Files

GET/api/files?path=/home

List files and directories at the given path.

Response

{
  "path": "/home",
  "entries": [
    { "name": "movies", "type": "directory", "size": 1234567890 },
    { "name": "config.yml", "type": "file", "size": 4096 }
  ]
}

GET

System

GET/api/system/stats

Get real-time CPU, memory, disk, and network statistics.

Response

{
  "cpu": { "usage": 23.5, "cores": 4 },
  "memory": { "used": 4831838208, "total": 8589934592 },
  "disk": { "used": 359661568000, "total": 536870912000 },
  "network": { "rx": 12300000, "tx": 4500000 }
}

GET

Scheduled Tasks

GET/api/tasks

List all scheduled cron tasks.

Response

[
  {
    "id": "backup-daily",
    "name": "Daily backup",
    "schedule": "0 2 * * *",
    "lastRun": "2024-01-15T02:00:00Z",
    "status": "ok"
  }
]