Introduction

The Oxide API is a REST API for the Oxide control plane. While you can use any HTTP client to interact with the API, most users prefer the SDKs, CLI, or web console.

Read Quick Start: CLI or Quick Start: Web for step-by-step instructions on how to create an API token, import an image, and create an instance.

Versioning

All API endpoints are at v1 at this time. Although certain API signatures may change between releases (e.g., to support additional request body or URL parameters), they are kept to v1 compatibility currently. You can continue to refer to the latest API documentation when using the v1 API. Any future version bump will be communicated in release notes and highlighted in change logs.

Authentication

Depending on the type of API client you use, you may authenticate to the Oxide rack with session cookies or device tokens. Please refer to the Authentication section for the details about these authentication methods.

Response codes

The Oxide API uses standard HTTP response codes. Read the Responses guide for more details.

Examples

Create disk from image

Use endpoint disk_create.

oxide api /v1/disks?project=myproj --method POST --input - << EOF
{
  "name"       : "boot-disk",
  "description": "from a silo image",
  "size"       : 4294967296,
  "disk_source": {
    "type": "image",
    "image_id": "$(oxide api '/v1/images/ubuntu-noble' | jq -r .id)"
  }
}
EOF

Create blank disk

Use endpoint disk_create.

oxide api /v1/disks?project=myproj --method POST --input - << EOF
{
  "name"       : "data-disk",
  "description": "blank disk for data storage",
  "size"       : 21474836480,
  "disk_source": {
    "type": "blank",
    "block_size": 4096
  }
}
EOF

Create instance with existing disks

Use endpoint instance_create.

oxide api /v1/instances?project=myproj --method POST --input - << EOF
{
  "name": "myinstance",
  "description": "my first Oxide instance",
  "hostname": "myinst",
  "memory": 4294967296,
  "ncpus": 2,
  "disks": [
    {
      "type": "attach",
      "name": "boot-disk"
    },
    {
      "type": "attach",
      "name": "data-disk"
    }
  ],
  "network_interfaces": {
    "type": "default"
  },
  "external_ips": [
    {
      "type": "ephemeral",
      "pool_name": "default"
    }
  ],
  "start": true
}
EOF

Create instance with new disks

Use endpoint instance_create.

oxide api /v1/instances?project=myproj --method POST --input - << EOF
{
  "name": "myinstance2",
  "description": "my second Oxide instance",
  "hostname": "myinst2",
  "memory": 4294967296,
  "ncpus": 2,
  "disks": [
    {
      "type": "create",
      "name": "ubuntu-disk",
      "description": "from a project image",
      "size": 4294967296,
      "disk_source": {
        "type": "image",
        "image_id": "$(oxide api '/v1/images/ubuntu-customized?project=myproj' | jq -r .id)"
      }
    },
    {
      "type": "create",
      "name": "additional-disk",
      "description": "blank disk for data storage",
      "size": 21474836480,
      "disk_source": {
        "type": "blank",
        "block_size": 4096
      }
    }
  ],
  "network_interfaces": {
    "type": "default"
  },
  "external_ips": [
    {
      "type": "ephemeral",
      "pool_name": "default"
    }
  ],
  "user_data": "$(cat mycloudinit.yaml | base64)",
  "start": true
}
EOF