API: Instances

Endpoints

Method	Path	Description
POST	`/v1/instances`	Create a new instance
GET	`/v1/instances`	List all instances
GET	`/v1/instances/{id}`	Get instance details
DELETE	`/v1/instances/{id}`	Delete an instance

## Create Instance

POST /v1/instances

Request Body

{
  "metadata": {
    "name": "web-server-01",
    "labels": {
      "env": "production",
      "team": "platform"
    }
  },
  "spec": {
    "type": "cx31",
    "image": "ubuntu-22.04",
    "vcpus": 2,
    "memory_mb": 4096,
    "disk_gb": 80,
    "vpc_id": "vpc-abc123",
    "subnet_id": "subnet-def456",
    "security_groups": ["sg-web", "sg-ssh"],
    "ssh_key_ids": ["key-001"],
    "user_data": "IyEvYmluL2Jhc2gKYXB0IHVwZGF0ZQ=="
  }
}

Response (201 Created)

{
  "id": "inst-a1b2c3",
  "metadata": {
    "name": "web-server-01",
    "labels": {"env": "production", "team": "platform"},
    "created_at": "2025-01-15T10:30:00Z"
  },
  "spec": {
    "type": "cx31",
    "image": "ubuntu-22.04",
    "vcpus": 2,
    "memory_mb": 4096,
    "disk_gb": 80,
    "vpc_id": "vpc-abc123",
    "subnet_id": "subnet-def456",
    "security_groups": ["sg-web", "sg-ssh"],
    "ssh_key_ids": ["key-001"],
    "user_data": "IyEvYmluL2Jhc2gKYXB0IHVwZGF0ZQ=="
  },
  "status": {
    "state": "provisioning",
    "host_id": "",
    "private_ip": "",
    "public_ip": ""
  },
  "operation_id": "op-xyz789"
}

InstanceSpec Fields

Field	Type	Required	Description
`type`	string	Yes	Server type identifier
`image`	string	Yes	OS image identifier
`vcpus`	int	No	Number of virtual CPUs
`memory_mb`	int	No	Memory in megabytes
`disk_gb`	int	No	Root disk size in gigabytes
`vpc_id`	string	No	VPC to attach the instance to
`subnet_id`	string	No	Subnet within the VPC
`security_groups`	string[]	No	List of security group IDs
`ssh_key_ids`	string[]	No	List of SSH key IDs
`user_data`	string	No	Base64-encoded cloud-init script

## InstanceStatus Fields

Field	Type	Description
`state`	string	Current state: provisioning, running, stopping, stopped, terminated
`host_id`	string	Physical host identifier
`private_ip`	string	Private IP address within the VPC
`public_ip`	string	Public IP address (if assigned)

## List Instances

GET /v1/instances

Response (200 OK)

{
  "items": [
    {
      "id": "inst-a1b2c3",
      "metadata": {"name": "web-server-01"},
      "spec": {"type": "cx31", "image": "ubuntu-22.04"},
      "status": {"state": "running", "private_ip": "10.0.1.15", "public_ip": "203.0.113.42"}
    }
  ]
}

Delete Instance

DELETE /v1/instances/inst-a1b2c3

Returns 202 with an operation ID for tracking the async deletion.