Skip to content
StratumStratum Docs

List instance types (customer-readable, operator-managed).

GET
/v1/compute/instance-types
Code sample: Shell / cURL
curl --request GET \
  --url 'https://stratum.example.com/v1/compute/instance-types?state=active&architecture=amd64' \
  --header 'Authorization: Bearer <token>'

Defaults to state=active so customers see only launchable types; pass ?state=all (operator-only Cedar gate) to include deprecated + removed entries.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
state
string
Allowed values: active deprecated removed all
architecture
string
Allowed values: amd64 arm64
hypervisorDriver
string

Responses

Section titled “Responses”

200

Section titled “200”

Instance types.

Media typeapplication/json

Complete: returns every instance type in the catalog.

This list is bounded by the install’s own configuration rather than by tenant activity, so it is not paginated and carries no nextPageToken. A client has the whole set in one response.

object
items
required
Array<object>
object
id
required
string
/^itype-[a-z0-9-]+$/
name
required

AWS-shaped catalog name (e.g. m1.large).

string
/^[a-z][a-z0-9]*\.[a-z0-9]+$/
displayName
string
description
string
vcpus
required
integer
>= 1
memoryBytes
required
integer format: int64
>= 1
networkPerformance

Human-readable network performance hint (e.g. up to 10 Gbps).

string
networkThroughputMbps

Enforced per-NIC bandwidth cap in Mbps. null (or omitted) means unlimited — the back-compat path for instance-type rows created before.

integer
nullable >= 1
diskIops

Enforced per-instance disk IOPS ceiling, the other half of ’s noisy-neighbour story: vCPU and memory are capped by the type, network by networkThroughputMbps, and until this landed disk by nothing at all. null (or omitted) means unlimited.

Applied by the hypervisor as a qemu-level throttle (<iotune>), so it holds for both Ceph RBD and node-local LVM-thin volumes.

Stamped at launch and not re-applied. Editing this on a type does not re-throttle instances already running on it — the same behaviour as networkThroughputMbps.

integer
nullable >= 1
diskThroughputMbps

Enforced per-instance disk bandwidth ceiling in megaBYTES per second. Note the deliberate unit difference from networkThroughputMbps, which is megaBITS: each follows the convention of its own domain. null (or omitted) means unlimited.

Capping one axis without the other is supported and useful — an IOPS ceiling with no bandwidth ceiling throttles a random-IO neighbour without slowing a large sequential restore.

integer
nullable >= 1
defaultRootVolumeBytes
integer format: int64
architecture
required
string
Allowed values: amd64 arm64
hypervisorDriver
required

Driver kind that can launch this type (libvirt-kvm, cloud-hypervisor, firecracker, fake).

string
state
required
string
Allowed values: active deprecated removed
tags

AWS-shape resource tags. Freeform UTF-8 keys (1-128 bytes, no leading/trailing whitespace) mapped to freeform UTF-8 values (0-256 bytes). Max 50 tags per resource. Reserved prefixes (stratum.dev/, stratum.platform_health., stratum:, aws:) return 400 RESERVED_NAMESPACE on customer input. PATCH replaces the whole map..

object
<= 50 properties
key
additional properties
string
<= 256 characters
createdAt
required
string format: date-time
updatedAt
required
string format: date-time

Example 

{
  "items": [
    {
      "architecture": "amd64",
      "state": "active"
    }
  ]
}