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

The API typically changes between system releases. Each release of the API is identified by the info.version field in its OpenAPI schema. The current version is 2025112000.0.0. Clients can tell the API which version they expect by sending an api-version header with each request:

api-version: 2025112000.0.0

The SDKs and CLI send this header automatically, using the version of the API schema they were generated from. If you call the API with your own HTTP client, you should set the header yourself. Requests without the header are assumed to target the latest version.

The version header is important because it tells the API how to handle requests from older clients, accepting request bodies and returning responses in the old format. This way, existing clients keep working after the control plane is updated — there is no need to upgrade clients in lockstep. If a request declares a version newer than the API supports (for example, a recently updated CLI talking to a system that has not been updated yet), it is rejected with an explicit version error.

Authentication

Depending on the type of API client you use, you may authenticate 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_backend": {
    "type": "distributed",
    "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_backend": {
    "type": "distributed",
    "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_ipv4"
  },
  "external_ips": [
    {
      "type": "ephemeral",
      "pool_selector": {
        "ip_version": "v4",
        "type": "auto"
      }
    }
  ],
  "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_backend": {
        "type": "distributed",
        "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_backend": {
        "type": "distributed",
        "disk_source": {
          "type": "blank",
          "block_size": 4096
        }
      }
    }
  ],
  "network_interfaces": {
    "type": "default_ipv4"
  },
  "external_ips": [
    {
      "type": "ephemeral",
      "pool_selector": {
        "ip_version": "v4",
        "type": "auto"
      }
    }
  ],
  "start": true
}
EOF