Exoscale instance API
Instances are the virtual machines at the core of the Exoscale Compute service.
OpenAPI Specification
openapi: 3.0.0
info:
version: 2.0.0
termsOfService: https://exoscale.com/terms
contact:
email: support@exoscale.com
name: Exoscale Support
url: https://portal.exoscale.com/tickets
title: Exoscale ai-api-key instance API
description: Infrastructure automation API, allowing programmatic access to all Exoscale products and services.
servers:
- url: https://api-{zone}.exoscale.com/v2
variables:
zone:
default: ch-gva-2
enum:
- ch-gva-2
- ch-dk-2
- de-fra-1
- de-muc-1
- at-vie-1
- at-vie-2
- bg-sof-1
- hr-zag-1
tags:
- description: "Instances are the virtual machines at the core of the Exoscale\n Compute service."
parent: compute
externalDocs:
description: Read more
url: https://www.exoscale.com/compute/
name: instance
x-display-name: Instance
x-weight: 110
x-icon: exo-vm
paths:
/instance/{id}:create-snapshot:
post:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Create a Snapshot of a Compute instance
operationId: create-snapshot
/instance/{id}:password:
get:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/instance-password'
description: "Reveal the password used during instance creation or the latest password reset.\n This is only available for VMs created against templates having the `password-enabled`\n property set to `true`.\n\n Passwords are transiently stored for at most 24 hours and intended to be retrieved shortly after\n creation or resets."
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Reveal the password used during instance creation or the latest password reset.
operationId: reveal-instance-password
/instance/{id}:resize-disk:
put:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: 'This operation resizes a Compute instance''s disk volume. Note: the disk can only grow, cannot be shrunk.'
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Resize a Compute instance disk
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
disk-size:
type: integer
format: int64
minimum: 10
maximum: 51200
exclusiveMinimum: false
exclusiveMaximum: false
description: Instance disk size in GiB
required:
- disk-size
operationId: resize-instance-disk
/instance/{id}:reset-password:
put:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Reset a compute instance password
operationId: reset-instance-password
/instance/{id}:start:
put:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: This operation starts a virtual machine, potentially using a rescue profile if specified
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Start a Compute instance
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
rescue-profile:
type: string
enum:
- netboot-efi
- netboot
description: 'Boot in Rescue Mode, using named profile (supported: netboot, netboot-efi)'
operationId: start-instance
/instance/{id}:enable-tpm:
post:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Enable tpm for the instance.
operationId: enable-tpm
/instance/{id}:scale:
put:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: 'This operation changes the Compute instance''s type. Note: the new Instance Type must be within the same family (e.g. a standard instance cannot be scaled to gpu2 or storage).'
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Scale a Compute instance to a new Instance Type
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
instance-type:
$ref: '#/components/schemas/instance-type-ref'
description: Instance Type
required:
- instance-type
operationId: scale-instance
/instance/{id}:stop:
put:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Stop a Compute instance
operationId: stop-instance
/instance/{id}:add-protection:
put:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Set instance destruction protection
operationId: add-instance-protection
/instance/{id}/{field}:
delete:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
- in: path
required: true
name: field
schema:
type: string
enum:
- labels
summary: Reset Instance field
operationId: reset-instance-field
/instance/{id}:remove-protection:
put:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Remove instance destruction protection
operationId: remove-instance-protection
/instance/{id}:reset:
put:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: 'This operation re-installs a Compute instance to a base template. If target template is provided it will be used to recreated instance from. Warning: the operation wipes all data stored on the disk.'
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Reset a Compute instance to a base/target template
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
template:
$ref: '#/components/schemas/template-ref'
description: Template to recreate Instance from
disk-size:
type: integer
format: int64
minimum: 10
maximum: 51200
exclusiveMinimum: false
exclusiveMaximum: false
description: Instance disk size in GiB
operationId: reset-instance
/console/{id}:
get:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
url:
type: string
host:
type: string
path:
type: string
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Retrieve signed url valid for 60 seconds to connect via console-proxy websocket to VM VNC console.
operationId: get-console-proxy-url
/instance/{id}:
delete:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Delete a Compute instance
operationId: delete-instance
put:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Update a Compute instance
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
maxLength: 255
minLength: 1
description: Instance name
user-data:
type: string
maxLength: 32768
minLength: 1
description: Instance Cloud-init user-data (base64 encoded)
public-ip-assignment:
$ref: '#/components/schemas/public-ip-assignment'
description: Assign public IP to the Instance
labels:
$ref: '#/components/schemas/labels'
description: Resource labels
nullable: true
application-consistent-snapshot-enabled:
type: boolean
description: Enable/Disable Application Consistent Snapshot for Instance
operationId: update-instance
get:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/instance'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Retrieve Compute instance details
operationId: get-instance
/instance/{id}:reboot:
put:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Reboot a Compute instance
operationId: reboot-instance
/instance:
post:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: ''
parameters: []
summary: Create a Compute instance
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
application-consistent-snapshot-enabled:
type: boolean
description: Enable application-consistent snapshot for the instance
anti-affinity-groups:
type: array
items:
$ref: '#/components/schemas/anti-affinity-group-ref'
uniqueItems: true
description: Instance Anti-affinity Groups
public-ip-assignment:
$ref: '#/components/schemas/public-ip-assignment'
description: Assign public IP to the Instance
labels:
$ref: '#/components/schemas/labels'
description: Resource labels
auto-start:
type: boolean
description: 'Start Instance on creation (default: true)'
security-groups:
type: array
items:
$ref: '#/components/schemas/security-group-ref'
uniqueItems: true
description: Instance Security Groups
name:
type: string
maxLength: 255
minLength: 1
description: Instance name
instance-type:
$ref: '#/components/schemas/instance-type-ref'
description: Instance Type
template:
$ref: '#/components/schemas/template-ref'
description: Instance Template
secureboot-enabled:
type: boolean
description: Enable secure boot
ssh-key:
$ref: '#/components/schemas/ssh-key-ref'
deprecated: true
description: Instance SSH Key
user-data:
type: string
maxLength: 32768
minLength: 1
description: Instance Cloud-init user-data (base64 encoded)
tpm-enabled:
type: boolean
description: Enable Trusted Platform Module (TPM)
deploy-target:
$ref: '#/components/schemas/deploy-target-ref'
description: Instance Deploy Target
ipv6-enabled:
type: boolean
description: 'Enable IPv6. DEPRECATED: use `public-ip-assignments`.'
disk-size:
type: integer
format: int64
minimum: 10
maximum: 51200
exclusiveMinimum: false
exclusiveMaximum: false
description: Instance disk size in GiB
ssh-keys:
type: array
items:
$ref: '#/components/schemas/ssh-key-ref'
uniqueItems: true
description: Instance SSH Keys
required:
- disk-size
- instance-type
- template
operationId: create-instance
get:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
instances:
type: array
items:
type: object
properties:
public-ip-assignment:
$ref: '#/components/schemas/public-ip-assignment'
description: Instance public IP assignment
labels:
$ref: '#/components/schemas/labels'
description: Resource labels
security-groups:
type: array
items:
$ref: '#/components/schemas/security-group'
description: Instance Security Groups
name:
type: string
maxLength: 255
minLength: 1
description: Instance name
instance-type:
$ref: '#/components/schemas/instance-type'
description: Instance Type
private-networks:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: Private Network ID
mac-address:
type: string
description: Private Network MAC address
description: Private Network
description: Instance Private Networks
template:
$ref: '#/components/schemas/template'
description: Instance Template
state:
$ref: '#/components/schemas/instance-state'
description: Instance state
ssh-key:
$ref: '#/components/schemas/ssh-key'
description: Instance SSH Key
mac-address:
type: string
description: Instance MAC address
manager:
$ref: '#/components/schemas/manager'
description: Instance manager
ipv6-address:
type: string
description: Instance IPv6 address
id:
type: string
format: uuid
description: Instance ID
ssh-keys:
type: array
items:
$ref: '#/components/schemas/ssh-key'
description: Instance SSH Keys
created-at:
type: string
format: date-time
description: Instance creation date
public-ip:
type: string
format: ipv4
description: Instance public IPv4 address
description: Instance
description: ''
parameters:
- in: query
required: false
name: manager-id
schema:
type: string
format: uuid
- in: query
required: false
name: manager-type
schema:
type: string
enum:
- instance-pool
- in: query
required: false
name: ip-address
schema:
type: string
- in: query
required: false
name: labels
schema:
type: string
summary: List Compute instances
operationId: list-instances
/instance/{instance-id}:revert-snapshot:
post:
tags:
- instance
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/operation'
description: 'This operation reverts the snapshot to the Compute instance volume, restoring stored data as it was at the time of the snapshot.
The Compute instance must be previously stopped.'
parameters:
- in: path
required: true
name: instance-id
schema:
type: string
format: uuid
summary: Revert a snapshot for an instance
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
description: Snapshot ID
required:
- id
operationId: revert-instance-to-snapshot
components:
schemas:
instance-type:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
description: Instance type ID
size:
type: string
enum:
- large
- huge
- jumbo
- medium
- mega
- small
- extra-large
- titan48c
- titan
- micro
- colossus
- tiny
readOnly: true
description: Instance type size
family:
type: string
enum:
- gpu3
- gpua30
- gpu3080ti
- gpu2
- gpu
- memory
- gpua5000
- gpurtx6000pro
- storage
- standard
- colossus
- cpu
readOnly: true
description: Instance type family
cpus:
type: integer
format: int64
minimum: 0
exclusiveMinimum: true
readOnly: true
description: CPU count
gpus:
type: integer
format: int64
minimum: 0
exclusiveMinimum: true
readOnly: true
description: GPU count
authorized:
type: boolean
readOnly: true
description: Requires authorization or publicly available
memory:
type: integer
format: int64
minimum: 0
exclusiveMinimum: true
readOnly: true
description: Available memory
zones:
type: array
items:
$ref: '#/components/schemas/zone-name'
readOnly: true
description: Instance Type available zones
description: Compute instance type
instance-type-ref:
type: object
properties:
id:
type: string
format: uuid
description: Instance type ID
description: Instance type reference
security-group-ref:
type: object
properties:
id:
type: string
format: uuid
description: Security group ID
description: Security group reference
public-ip-assignment:
type: string
enum:
- inet4
- dual
- none
template-ref:
type: object
properties:
id:
type: string
format: uuid
description: Template ID
description: Template reference
zone-name:
type: string
enum:
- ch-dk-2
- de-muc-1
- ch-gva-2
- at-vie-1
- de-fra-1
- bg-sof-1
- at-vie-2
- hr-zag-1
instance:
type: object
properties:
application-consistent-snapshot-enabled:
type: boolean
description: Indicates if the instance will take application-consistent snapshots
anti-affinity-groups:
type: array
items:
$ref: '#/components/schemas/anti-affinity-group-ref'
description: Instance Anti-affinity Groups
public-ip-assignment:
$ref: '#/components/schemas/public-ip-assignment'
description: Instance public IP assignment
labels:
$ref: '#/components/schemas/labels'
description: Resource labels
security-groups:
type: array
items:
$ref: '#/components/schemas/security-group-ref'
description: Instance Security Groups
elastic-ips:
type: array
items:
$ref: '#/components/schemas/elastic-ip-ref'
description: Instance Elastic IPs
name:
type: string
maxLength: 255
minLength: 1
description: Instance name
instance-type:
$ref: '#/components/schemas/instance-type'
description: Instance Type
private-networks:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: Private Network ID
mac-address:
type: string
description: Private Network MAC address
description: Private Network
description: Instance Private Networks
template:
$ref: '#/components/schemas/template'
description: Instance Template
state:
$ref: '#/components/schemas/instance-state'
readOnly: true
description: Instance state
secureboot-enabled:
type: boolean
description: Indicates if the instance has secure boot enabled
ssh-key:
$ref: '#/components/schemas/ssh-key'
description: Instance SSH Key
user-data:
type: string
minLength: 1
description: Instance Cloud-init user-data (base64 encoded)
mac-address:
type: string
readOnly: true
description: Instance MAC address
manager:
$ref: '#/components/schemas/manager'
readOnly: true
description: Instance manager
tpm-enabled:
type: boolean
description: Indicates if the instance has tpm enabled
deploy-target:
$ref: '#/components/schemas/deploy-target-ref'
description: Instance Deploy Target
ipv6-address:
type: string
readOnly: true
description: Instance IPv6 address
id:
type: string
format: uuid
readOnly: true
description: Instance ID
snapshots:
type: array
items:
$ref: '#/components/schemas/snapshot-ref'
description: Instance Snapshots
disk-size:
type: integer
format: int64
minimum: 10
maximum: 51200
exclusiveMinimum: false
exclusiveMaximum: false
description: Instance disk size in GiB
ssh-keys:
type: array
items:
$ref: '#/components/schemas/ssh-key'
description: Instance SSH Keys
created-at:
type: string
format: date-time
readOnly: true
description: Instance creation date
public-ip:
type: string
format: ipv4
readOnly: true
description: Instance public IPv4 address
description: Instance
snapshot-ref:
type: object
properties:
id:
type: string
format: uuid
description: Snapshot ID
description: Snapshot reference
operation:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
description: Operation ID
reason:
type: string
enum:
- incorrect
- unknown
- unavailable
- forbidden
- busy
- fault
- partial
- not-found
- interrupted
- unsupported
- conflict
readOnly: true
description: Operation failure reason
reference:
type: object
properties:
id:
type: string
format: uuid
description: Reference ID
link:
type: string
readOnly: true
description: Link to the referenced resource
command:
type: string
description: Command name
description: Related resource reference
readOnly: true
message:
type: string
readOnly: true
description: Operation message
state:
type: string
enum:
- failure
- pending
- success
- timeout
readOnly: true
description: Operation status
description: Operation
deploy-target-ref:
type: object
properties:
id:
type: string
format: uuid
description: Deploy target ID
description: Deploy target reference
ssh-key-ref:
type: object
properties:
name:
type: string
maxLength: 255
minLength: 1
description: SSH key name
description: SSH key reference
instance-password:
type: object
properties:
password:
type: string
readOnly: true
description: Password
description: Instance password
manager:
type: object
properties:
id:
type: string
format: uuid
description: Manager ID
type:
type: string
enum:
- sks-nodepool
- instance-pool
description: Manager type
description: Resource manager
security-group-resource:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
description: Security Group ID
name:
type: string
maxLength: 255
minLength: 1
description: Security Group name
visibility:
type: string
enum:
- private
- public
description: "Whether this points to a public security group. This is only valid when in the context of\n a rule addition which uses a public security group as a source or destination."
description: Security Group
labels:
type: object
additionalProperties:
type: string
security-group-rule:
type: object
properties:
description:
type: string
maxLength: 255
description: Security Group rule description
start-port:
type: integer
format: int64
minimum: 1
maximum: 65535
exclusiveMinimum: false
exclusiveMaximum: false
description: Start port of the range
protocol:
type: string
enum:
- tcp
- esp
- icmp
- udp
- gre
- ah
- ipip
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/exoscale/refs/heads/main/openapi/exoscale-instance-api-openapi.yml