API Reference¶

REST API documentation for Machineuse.

Base URL¶

http://localhost:8000

Authentication¶

Default Configuration

Authentication is disabled by default. Enable it in production by setting auth_enabled: true in your configuration.

When enabled, include the API key in requests:

curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:8000/v2/instances

Health Check¶

GET /health¶

Check service health.

Response:

{
  "status": "healthy",
  "instances_count": 15,
  "running_instances": 12
}

Instances¶

POST /v2/instances¶

Create a new instance.

Request Body:

{
  "image": "ubuntu:22.04",
  "config": {
    "memory_gb": 2,
    "cpu_cores": 2,
    "disk_gb": 10,
    "idle_timeout_minutes": 30,
    "auto_snapshot": true
  },
  "node_preference": "worker-1"
}

Response:

{
  "id": "abc123def456",
  "status": "creating",
  "node_id": "worker-1",
  "subdomain": "a1b2c3d4",
  "debug_port": 9222,
  "stream_port": 5000,
  "http_port": 8080,
  "created_at": "2026-03-19T10:30:00Z",
  "urls": {
    "debug": "http://a1b2c3d4.example.com/debug/",
    "stream": "http://a1b2c3d4.example.com/stream"
  }
}

GET /v2/instances¶

List all instances.

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status
`node_id`	string	Filter by node
`limit`	integer	Max results (default: 100)
`offset`	integer	Pagination offset

Response:

{
  "instances": [
    {
      "id": "abc123def456",
      "status": "running",
      "node_id": "worker-1",
      "subdomain": "a1b2c3d4",
      "debug_port": 9222,
      "stream_port": 5000,
      "created_at": "2026-03-19T10:30:00Z",
      "resources": {
        "cpu_percent": 15.2,
        "memory_mb": 512,
        "disk_mb": 1024
      }
    }
  ],
  "total": 15,
  "limit": 100,
  "offset": 0
}

GET /v2/instances/{instance_id}¶

Get instance details.

Path Parameters:

Parameter	Type	Description
`instance_id`	string	Instance ID

Response:

{
  "id": "abc123def456",
  "status": "running",
  "node_id": "worker-1",
  "subdomain": "a1b2c3d4",
  "debug_port": 9222,
  "stream_port": 5000,
  "http_port": 8080,
  "created_at": "2026-03-19T10:30:00Z",
  "config": {
    "memory_gb": 2,
    "cpu_cores": 2,
    "disk_gb": 10
  },
  "resources": {
    "cpu_percent": 15.2,
    "memory_mb": 512,
    "disk_mb": 1024
  },
  "activity": {
    "last_activity": "2026-03-19T10:45:00Z",
    "idle_minutes": 5
  }
}

DELETE /v2/instances/{instance_id}¶

Delete an instance.

Query Parameters:

Parameter	Type	Description
`force`	boolean	Skip graceful shutdown

Response:

{
  "message": "Instance deleted successfully"
}

POST /v2/instances/{instance_id}/dormant¶

Make an instance dormant.

Response:

{
  "id": "abc123def456",
  "status": "dormant",
  "snapshot_id": "snap_xyz789",
  "dormant_since": "2026-03-19T11:00:00Z"
}

POST /v2/instances/{instance_id}/revive¶

Revive a dormant instance.

Request Body:

{
  "method": "quick_start"
}

Response:

{
  "id": "abc123def456",
  "status": "reviving",
  "estimated_completion": "2026-03-19T11:01:00Z"
}

Nodes¶

GET /v2/nodes¶

List all worker nodes.

Response:

{
  "nodes": [
    {
      "id": "worker-1",
      "status": "online",
      "address": "tcp://192.168.1.10:5555",
      "instances_count": 15,
      "max_instances": 50,
      "resources": {
        "cpu_percent": 45.0,
        "memory_percent": 62.0,
        "disk_percent": 30.0
      },
      "last_heartbeat": "2026-03-19T10:59:30Z"
    }
  ]
}

GET /v2/nodes/{node_id}¶

Get node details.

Response:

{
  "id": "worker-1",
  "status": "online",
  "address": "tcp://192.168.1.10:5555",
  "instances_count": 15,
  "max_instances": 50,
  "capabilities": {
    "cpu_cores": 8,
    "memory_gb": 32,
    "disk_gb": 500
  },
  "resources": {
    "cpu_percent": 45.0,
    "memory_percent": 62.0,
    "disk_percent": 30.0
  }
}

Metrics¶

GET /v2/metrics¶

Get cluster metrics.

Query Parameters:

Parameter	Type	Description
`node_id`	string	Filter by node
`period`	string	Time period (1h, 24h, 7d)

Response:

{
  "cluster": {
    "total_instances": 38,
    "running_instances": 35,
    "dormant_instances": 3,
    "avg_cpu_percent": 56.0,
    "avg_memory_percent": 70.0
  },
  "timeseries": {
    "timestamps": ["2026-03-19T10:00:00Z", "..."],
    "cpu": [45.0, 52.0, "..."],
    "memory": [65.0, 68.0, "..."]
  }
}

Error Responses¶

All errors follow this format:

{
  "detail": "Error message description",
  "code": "ERROR_CODE"
}

HTTP Status Codes¶

Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing authentication
404	Not Found - Resource not found
409	Conflict - Resource state conflict
500	Internal Server Error
503	Service Unavailable

Rate Limiting¶

Note

Rate limiting is not enabled by default. Configure it for production use.

When enabled, responses include:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1679234400

Webhooks¶

Configure webhooks for instance events:

{
  "url": "https://your-server.com/webhook",
  "events": ["instance.created", "instance.deleted", "instance.dormant"],
  "secret": "your-webhook-secret"
}

Event payload:

{
  "event": "instance.created",
  "timestamp": "2026-03-19T10:30:00Z",
  "data": {
    "instance_id": "abc123def456",
    "status": "creating"
  }
}