REST API

Observe and control services from IDE plugins, desktop apps, and CLI tools.

The API server is embedded in the fuku process and available during fuku run. Disabled by default. All endpoints except /api/v1/live and /api/v1/ready require Authorization: Bearer <token> header.

Field	Description
`server.listen`	TCP address to bind (must be loopback)
`server.auth.token`	Bearer token for authentication

fuku.yaml

server:
  listen: "127.0.0.1:9876"
  auth:
    token: "my-dev-token"

Base URL

Token

GET /api/v1/live

Liveness probe. Returns 200 when the API server is reachable. No authentication required.

Response 200

{ "status": "alive" }

GET /api/v1/ready

Readiness probe. Returns 200 once the runtime store has received profile data, 503 before that. No authentication required.

Response 200

{ "status": "ready" }

Response 503

{ "status": "not ready" }

GET /api/v1/status

Returns fuku instance information: version, profile, phase, uptime, and service counts.

Response 200

{
  "version": "0.18.0",
  "profile": "default",
  "phase": "running",
  "uptime": 3600,
  "services": {
    "total": 8,
    "starting": 0,
    "running": 6,
    "stopping": 0,
    "restarting": 0,
    "stopped": 1,
    "failed": 1
  }
}

Response 401

{ "error": "unauthorized" }

Response 500

{ "error": "internal server error" }

GET /api/v1/services

Returns all services in the active profile, ordered by tier then name.

Response 200

{
  "services": [
    {
      "id": "550e8400-...",
      "name": "api-gateway",
      "tier": "foundation",
      "status": "running",
      "watching": true,
      "pid": 12345,
      "cpu": 2.4,
      "memory": 67108864,
      "uptime": 3600
    }
  ]
}

Response 401

{ "error": "unauthorized" }

Response 500

{ "error": "internal server error" }

GET /api/v1/services/:id

Returns a single service by UUID.

Response 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "api-gateway",
  "tier": "foundation",
  "status": "running",
  "watching": true,
  "pid": 12345,
  "cpu": 2.4,
  "memory": 67108864,
  "uptime": 3600
}

Response 401

{ "error": "unauthorized" }

Response 404

{ "error": "service not found" }

Response 500

{ "error": "internal server error" }

Service ID

POST /api/v1/services/:id/start

Starts a stopped or failed service. Asynchronous — poll GET /services/:id for completion.

Response 202

{
  "id": "550e8400-...",
  "name": "api-gateway",
  "action": "start",
  "status": "starting"
}

Response 401

{ "error": "unauthorized" }

Response 404

{ "error": "service not found" }

Response 409

{ "error": "service cannot be started" }

Response 409

{ "error": "instance is not accepting actions" }

Response 500

{ "error": "internal server error" }

Service ID

POST /api/v1/services/:id/stop

Stops a running service. Asynchronous — poll GET /services/:id for completion.

Response 202

{
  "id": "550e8400-...",
  "name": "api-gateway",
  "action": "stop",
  "status": "stopping"
}

Response 401

{ "error": "unauthorized" }

Response 404

{ "error": "service not found" }

Response 409

{ "error": "service is not running" }

Response 409

{ "error": "instance is not accepting actions" }

Response 500

{ "error": "internal server error" }

Service ID

POST /api/v1/services/:id/restart

Restarts a running, stopped, or failed service. Asynchronous — poll GET /services/:id for completion.

Response 202

{
  "id": "550e8400-...",
  "name": "api-gateway",
  "action": "restart",
  "status": "restarting"
}

Response 401

{ "error": "unauthorized" }

Response 404

{ "error": "service not found" }

Response 409

{ "error": "service cannot be restarted" }

Response 409

{ "error": "instance is not accepting actions" }

Response 500

{ "error": "internal server error" }

Service ID

ERR Common Errors

Status	Error	When
`401`	unauthorized	Missing or invalid bearer token
`404`	service not found	Unknown UUID
`409`	service cannot be started	Start on non-stopped service
`409`	service is not running	Stop on non-running service
`409`	service cannot be restarted	Restart on starting/stopping/restarting service
`409`	instance is not accepting actions	Action during startup or shutdown