Servers

Servers are Fugoku's unified compute resource, covering both bare metal and virtual machines. They are modeled after the Latitude.sh server API and use JSON:API formatting.

Server Roles

Role	Description
`BareMetal`	Dedicated physical server with IPMI access
`VirtualMachine`	Virtualized instance running on shared hardware

List Servers

GET /v1/servers

Returns a paginated list of servers for the authenticated project. Includes both bare metal and virtual machines.

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`sort`	string	Sort field: `createdAt`, `hostname`, `status`, `site`
`fields[servers]`	string	Comma-separated fields to include

Example:

curl "https://api.fugoku.com/v1/servers?page=1&limit=20&sort=createdAt" \
  -H "Authorization: Bearer $TOKEN"

Get Server

GET /v1/servers/:id

Returns a single server by ID.

Create Server

POST /v1/servers

Creates a new server from the server catalog. Use role: "VirtualMachine" to create a VM instead of bare metal.

Request Body (JSON:API format):

{
  "data": {
    "type": "servers",
    "attributes": {
      "name": "my-server",
      "hostname": "my-server.example.com",
      "project": "default",
      "site": "NYC",
      "plan": "rs4.metal.large",
      "operating_system": "ubuntu-24.04",
      "billing": "hourly",
      "ssh_keys": ["key-abc123"],
      "user_data": "#cloud-init\n...",
      "tags": [{ "key": "env", "value": "production" }],
      "role": "VirtualMachine",
      "provider": "latitude",
      "worker_count": 1,
      "spot": false,
      "accelerators": "A100:1"
    }
  }
}

Field	Type	Required	Description
`name`	string	Yes	Server name (1–64 chars)
`hostname`	string	Yes	Server hostname
`site`	string	Yes	Data center site
`plan`	string	Yes	Plan slug from catalog
`operating_system`	string	Yes	OS slug from catalog
`billing`	string	Yes	`hourly`, `monthly`, or `yearly`
`ssh_keys`	array	No	SSH key slugs to inject
`user_data`	string	No	Cloud-init script
`tags`	array	No	Key-value tags
`role`	string	No	`BareMetal` or `VirtualMachine`
`provider`	string	No	Provider ID (required for VMs)
`worker_count`	integer	No	Number of workers (VMs)
`spot`	boolean	No	Use spot pricing (VMs)
`accelerators`	string	No	GPU accelerators (VMs)

Example:

curl -X POST https://api.fugoku.com/v1/servers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "servers",
      "attributes": {
        "name": "my-server",
        "hostname": "my-server.example.com",
        "site": "NYC",
        "plan": "rs4.metal.large",
        "operating_system": "ubuntu-24.04",
        "billing": "hourly"
      }
    }
  }'

Response (201 Created):

{
  "data": {
    "id": "srv-abc123",
    "type": "servers",
    "attributes": {
      "hostname": "my-server.example.com",
      "label": "my-server",
      "status": "creating",
      "ipmiStatus": "Normal",
      "role": "BareMetal",
      "site": "NYC",
      "locked": false,
      "rescueAllowed": false,
      "billing": "hourly"
    }
  }
}

Update Server

PATCH /v1/servers/:id

Update label, locked, tags, or plan. Changing the plan triggers a migration and sets status to migrating.

Request body:

{
  "data": {
    "type": "servers",
    "attributes": {
      "label": "new-label",
      "locked": true,
      "tags": [{ "key": "env", "value": "staging" }],
      "plan": "m4.metal.xlarge"
    }
  }
}

Delete Server

DELETE /v1/servers/:id

Returns 204 No Content. The server is marked for deletion and scheduled for removal.

Server Actions

POST /v1/servers/:id/actions

Request body:

{
  "data": {
    "type": "actions",
    "attributes": {
      "action": "power_on"
    }
  }
}

Allowed actions: power_on, power_off, reboot

Example:

curl -X POST https://api.fugoku.com/v1/servers/srv-abc123/actions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "actions",
      "attributes": { "action": "power_off" }
    }
  }'

Server Backups

List Server Backups

GET /v1/servers/:id/backups

Returns backups for a bare metal server.

Create Server Backup

POST /v1/servers/:id/backups

Request body:

{
  "data": {
    "type": "backups",
    "attributes": {
      "name": "backup-before-upgrade"
    }
  }
}

Restore Backup

POST /v1/backups/:id/restore

Creates a new server from a backup. The original backup is archived.

Delete Backup

DELETE /v1/backups/:id

Returns 204 No Content. Backup is archived.

Server Status Values

Value	Description
`active`	Running
`creating`	Provisioning
`deleting`	Deletion in progress
`error`	Error state
`inactive`	Powered off
`installing`	OS installation
`maintenance`	Maintenance mode
`pending`	Queued for provisioning
`rescued`	Rescue mode
`rescuing`	Entering rescue mode
`restarted`	Recently rebooted
`scheduled`	Scheduled for action
`starting`	Booting
`stopped`	Powered off
`stopping`	Shutting down
`suspended`	Suspended
`terminated`	Permanently deleted
`updating`	Firmware/OS update
`waiting`	Waiting for resources

Server Roles

Value	Description
`BareMetal`	Dedicated physical server
`VirtualMachine`	Virtualized instance

Servers

On this page