The Oxide API is a set of REST APIs that interacts with the Oxide control plane. It follows common HTTP standards such as action verbs and response codes. The response body is in JSON format.
The Oxide API is based on the OpenAPI specification which allows developers to generate API clients and documentation in different programming languages using available OpenAPI tools. This API documentation is generated using the Oxide dropshot Rust program.
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.
Resource identifiers in requests
View, update, and delete APIs operate on specific resources, one resource per request. In general, the resource name or id is part of the path. Additional query criteria are passed as URL parameters if the name alone does not uniquely identify the resource. For example, you can use either of the following query syntax to specify a disk:
/v1/disks/mydisk?project=myproj /v1/disks/f449583f-23f6-4fab-b791-4cfe5766017c
You will notice that API endpoints are silo-specific. If you are a member of multiple silos, you will need to specify the silo target in your request profile (e.g. using the OXIDE_HOST environment variable) as the scope. Except for system-wide resources that are managed by the fleet administrators, the API path and query parameters are always confined to the silo in context.
Response codes
The Oxide API follows standard HTTP error and response codes. Please see the Responses section for more details.